Skip to content
Compositions

PromptPanel

Floating panel root - a shadowed card that prompts the user to pick an action or describe one. Compose it with PromptPanelHeader and PromptPanelBody (which stacks PromptPanelOption/PromptPanelFreeform rows); use PromptPanelStage around the body to animate between steps.

Usage

import { PromptPanel, promptPanelAnatomy, PromptPanelBody, PromptPanelBodyProps, PromptPanelFreeform, PromptPanelFreeformProps, PromptPanelHeader, PromptPanelHeaderProps, PromptPanelOption, PromptPanelOptionProps, PromptPanelProps, PromptPanelStage, PromptPanelStageProps, PromptPanelView, PromptPanelViewOption, PromptPanelViewProps, usePromptPanelKeyboard, UsePromptPanelKeyboardOptions, UsePromptPanelKeyboardResult } from "@instruments/materia-ui/compositions/prompt-panel";

Best practices

  • Pass title (or an explicit aria-label) - the panel is a role="dialog" surface floating over other content, so it needs an accessible name of its own.

  • Wrap step transitions in PromptPanelStage, not a hand-rolled page swap - it owns the page-slide choreography and the reduced-motion fallback.

Props

PromptPanel

PropTypeDefaultDescription
testIdstring

PromptPanelFreeform

PropTypeDefaultDescription
defaultValuestring""

Uncontrolled initial value.

iconIconComponentPencil

Leading icon.

inputRefReact.Ref<HTMLInputElement | null>

Ref forwarded to the underlying <input> (object or callback).

onSubmit((value: string) => void) | undefined

Called with the current value when Enter is pressed on non-empty text.

onValueChange((value: string) => void) | undefined

Called with the next value on every keystroke (controlled or uncontrolled).

shortcutReact.ReactNodea CornerDownLeft icon

Trailing Kbd content.

valuestring | undefined

Controlled value; omit for uncontrolled usage via defaultValue.

PromptPanelHeader

PropTypeDefaultDescription
children(required)React.ReactNode

Title copy, centred regardless of whether the back button is shown.

backLabelstring"Back"

Accessible label for the back button.

onBack(() => void) | undefined

Called when the back button is pressed.

showBackbooleanfalse

Show the leading back button.

PromptPanelOption

PropTypeDefaultDescription
children(required)React.ReactNode

Option label.

highlightedbooleanfalse

Keyboard-hover state - visually matches :hover for roving keyboard focus.

shortcut(required)string | number

Digit shown in the leading Kbd (matches usePromptPanelKeyboard's 1–9 shortcuts).

PromptPanelStage

PropTypeDefaultDescription
children(required)React.ReactNode

The current step's content - swap it whenever stepKey changes.

classNamestring
direction0 | 1 | -10

Which way the transition travels: 1 (deeper - enters from the right / page 2), -1 (back - enters from the left / page 1), or 0 (snap, no directional bias; used on first mount).

stepKey(required)string

Identifies the current step; changing it triggers the transition.

PromptPanelView

PropTypeDefaultDescription
freeformPlaceholderstring

Placeholder for the freeform row.

freeformValuestring

Controlled value for the freeform row; omit for uncontrolled usage.

highlightedOptionIdstring | null

Option id currently highlighted by keyboard navigation, if any.

onBack() => void

Called when the back button is pressed, or Backspace on an empty freeform.

onEscape() => void

Called when Escape is pressed in the freeform input.

onFreeformChange(value: string) => void

Called with the next value on every freeform keystroke.

onSelectOption(required)(id: string) => void

Called with the option's id when a row is selected.

onSubmitFreeform(required)(text: string) => void

Called with the freeform text when it's submitted.

options(required)PromptPanelViewOption[]

Selectable option rows, in display order.

showBackbooleanfalse

Show the leading back button.

title(required)string

Panel/step title.

Also exports

  • constpromptPanelAnatomy
  • componentPromptPanelBody
  • typePromptPanelBodyProps
  • typePromptPanelFreeformProps
  • typePromptPanelHeaderProps
  • typePromptPanelOptionProps
  • typePromptPanelProps
  • interfacePromptPanelStageProps
  • interfacePromptPanelViewOption
  • interfacePromptPanelViewProps
  • constusePromptPanelKeyboard
  • interfaceUsePromptPanelKeyboardOptions
  • interfaceUsePromptPanelKeyboardResult

Anatomy

PromptPanel

prompt-panel

Floating panel prompting the user to pick an action or describe one

PromptPanelHeader

prompt-panel-header

Centered title with an optional leading back button

PromptPanelBody

prompt-panel-body

Stacked option/freeform rows

PromptPanelOption

prompt-panel-option

Selectable row: icon, label, trailing Kbd digit

PromptPanelFreeform

prompt-panel-freeform

Borderless freeform text row with a submit Kbd

Composition

Builds on

Button, Flex, Grid, Icon, Kbd, Stack