Skip to content

components/palette/PaletteList

import { … } from 'zidane-ui'ui/src/components/palette/PaletteList.tsx

Components#

MatchedTitleComponent#

A title with its match. The match is shown when it reads as the words typed (one run per word): those runs in full weight and color, the rest of the title quieter. Letters picked across the title are not shown.

TypeScript
function MatchedTitle(props: MatchedTitleProps): Element
Parameters
NameTypeDescription
propsMatchedTitleProps

Component props.

Element
MatchedTitle props
NameTypeDescription
indicesreadonly number[]

Indices of the matched characters in text.

termsnumber

Number of words in the query. The match shows only when it forms at most that many runs.

textstring

The title to show.

ui/src/components/palette/PaletteList.tsx:290

PaletteIconComponent#

The item's glyph in the icon slot, quiet until its row is marked.

TypeScript
function PaletteIcon(props: PaletteIconProps): Element
Parameters
NameTypeDescription
propsPaletteIconProps

Component props.

Element
PaletteIcon props
NameTypeDescription
className?string

Extra classes on the root element.

icon?string

Icon class. A small dot shows when omitted.

style?CSSProperties

Inline styles on the root element, merged after the component's own.

ui/src/components/palette/PaletteList.tsx:388

PaletteListComponent#

Renders the palette's results: titled sections of rows in a listbox, windowed so only the rows in view are mounted. A block under the rows glides to the marked row.

TypeScript
function PaletteList<T extends PaletteEntry>(props: PaletteListProps<T>): Element
Type parameters
NameTypeDescription
Textends PaletteEntry
Parameters
NameTypeDescription
propsPaletteListProps<T>

Component props.

Element
PaletteList props
NameTypeDefaultDescription
className?string

Extra classes on the root element.

cursornumber

Flat index of the marked row, across sections. The list scrolls to keep it in view.

groupsreadonly PaletteSection<T>[]

The ranked sections to show.

nestedboolean

A picker's level: its toggle rows are choices (a check), not settings (a switch).

onHover(index: number) => void

Called with a row's flat index when the pointer moves over it.

onRun(row: PaletteRowData<T>) => void

Called with the row when it is clicked.

querystring

The current query. Its word count decides whether a title match is shown.

renderIcon?(row: PaletteRowData<T>) => ReactNode

The default row's icon; else a dot.

renderKeys?PaletteKeysdefaultPaletteKeys

Draws a keybinding spec as keycaps.

renderRow?(props: PaletteRowProps<T>) => ReactNode

Draws a row; return undefined for the default row. Keep it stable (rows are memoized on their props).

style?CSSProperties

Inline styles on the root element, merged after the component's own.

ui/src/components/palette/PaletteList.tsx:132

PaletteOptionComponent#

One palette option: a menu row with listbox semantics (focus stays in the query input).

TypeScript
function PaletteOption<T extends PaletteEntry>(props: PaletteOptionProps<T>): Element
Type parameters
NameTypeDescription
Textends PaletteEntry
Parameters
NameTypeDescription
propsPaletteOptionProps<T>

The row's PaletteRowProps plus the icon, title, description, trailing, toggle and checked props of a MenuRow.

Element
PaletteOption props
NameTypeDescription
activefrom PaletteRowPropsboolean

Whether the cursor is on this row.

checked?from Pickboolean

The current choice: a check in the trailing slot.

choicefrom PaletteRowPropsboolean

In a picker: a checked row is the current choice.

className?string

Extra classes on the root element.

description?from PickReactNode

Secondary text after the title. Inline it truncates to one line; size="lg" stacks it under the title, clamped to two lines.

icon?from PickReactNode

Leading glyph, drawn muted. Use it only when it means something (a kind, a folder). No icon slot renders when omitted.

indexfrom PaletteRowPropsnumber

Position of the row in the whole list, across sections.

onHoverfrom PaletteRowProps(index: number) => void

Called with the row's index when the pointer moves over it.

onRunfrom PaletteRowProps(row: PaletteRowData<T>) => void

Called with the row when it is clicked.

rowfrom PaletteRowPropsPaletteRowData<T>

The row's item and title matches.

style?CSSProperties

Inline styles on the root element, merged after the component's own.

termsfrom PaletteRowPropsnumber

Words in the query: a title match is shown when each reads as one run.

titlefrom PickReactNode

The row's label.

toggle?from Pickboolean

An on/off option: a switch in the trailing slot (use with role="menuitemcheckbox").

topfrom PaletteRowPropsnumber

Offset inside its section.

trailing?from PickReactNode

Content at the row's end, such as a keycap or a meta value. A check or switch from checked or toggle follows it.

ui/src/components/palette/PaletteList.tsx:334

PaletteRowComponent#

The default row: icon, matched title, detail when marked, then a switch, a check, a caret or the shortcut.

TypeScript
const PaletteRow: MemoExoticComponent<(props: PaletteRowProps<PaletteEntry> & Pick<PaletteOptionProps<PaletteEntry>, 'className' | 'style'> & { renderIcon?: (row: PaletteRowData) => ReactNode; renderKeys?: PaletteKeys }) => Element>

ui/src/components/palette/PaletteList.tsx:399

Constants#

defaultPaletteKeysConstant#

The default PaletteKeys: a small KeyCombo for the binding spec.

TypeScript
const defaultPaletteKeys: PaletteKeys

ui/src/components/palette/PaletteList.tsx:95

Interfaces#

MatchedTitlePropsInterface#

Props for MatchedTitle.

TypeScript
interface MatchedTitleProps
MatchedTitleProps properties
NameTypeDescription
indicesreadonly number[]

Indices of the matched characters in text.

termsnumber

Number of words in the query. The match shows only when it forms at most that many runs.

textstring

The title to show.

ui/src/components/palette/PaletteList.tsx:274

PaletteEntryInterface#

What a palette row shows. Structural, so an app's own item type fits as is.

TypeScript
interface PaletteEntry
PaletteEntry properties
NameTypeDescription
checked?boolean

Current state of a toggle item: on, or the current choice in a picker.

description?string

Detail text. It shows while the row is marked, or when the query matched only the description.

disabled?string

Why the row can't run; the row reads as disabled and shows it as a tooltip.

idstring

Stable identifier of the item.

keybinding?string

Shown on the marked row, as keycaps.

kind?string

toggle: a setting (a switch; a check in a picker). picker: opens a nested list (a caret).

titlestring

The row's label. The query is matched against it.

ui/src/components/palette/PaletteList.tsx:33

PaletteIconPropsInterface#

Props for PaletteIcon.

TypeScript
interface PaletteIconProps
PaletteIconProps properties
NameTypeDescription
className?string

Extra classes on the root element.

icon?string

Icon class. A small dot shows when omitted.

style?CSSProperties

Inline styles on the root element, merged after the component's own.

ui/src/components/palette/PaletteList.tsx:374

PaletteListPropsInterface#

Props of PaletteList.

TypeScript
interface PaletteListProps<T extends PaletteEntry = PaletteEntry>
PaletteListProps type parameters
NameTypeDefaultDescription
Textends PaletteEntryPaletteEntry
PaletteListProps properties
NameTypeDefaultDescription
className?string

Extra classes on the root element.

cursornumber

Flat index of the marked row, across sections. The list scrolls to keep it in view.

groupsreadonly PaletteSection<T>[]

The ranked sections to show.

nestedboolean

A picker's level: its toggle rows are choices (a check), not settings (a switch).

onHover(index: number) => void

Called with a row's flat index when the pointer moves over it.

onRun(row: PaletteRowData<T>) => void

Called with the row when it is clicked.

querystring

The current query. Its word count decides whether a title match is shown.

renderIcon?(row: PaletteRowData<T>) => ReactNode

The default row's icon; else a dot.

renderKeys?PaletteKeysdefaultPaletteKeys

Draws a keybinding spec as keycaps.

renderRow?(props: PaletteRowProps<T>) => ReactNode

Draws a row; return undefined for the default row. Keep it stable (rows are memoized on their props).

style?CSSProperties

Inline styles on the root element, merged after the component's own.

ui/src/components/palette/PaletteList.tsx:98

PaletteOptionPropsInterface#

Props for PaletteOption: the row's PaletteRowProps plus the icon, title, description, trailing, toggle and checked props of a MenuRow.

TypeScript
interface PaletteOptionProps<T extends PaletteEntry = PaletteEntry> extends PaletteRowProps<T>, Pick<MenuRowProps, 'icon' | 'title' | 'description' | 'trailing' | 'toggle' | 'checked'>
PaletteOptionProps type parameters
NameTypeDefaultDescription
Textends PaletteEntryPaletteEntry
PaletteOptionProps properties
NameTypeDescription
activefrom PaletteRowPropsboolean

Whether the cursor is on this row.

checked?from Pickboolean

The current choice: a check in the trailing slot.

choicefrom PaletteRowPropsboolean

In a picker: a checked row is the current choice.

className?string

Extra classes on the root element.

description?from PickReactNode

Secondary text after the title. Inline it truncates to one line; size="lg" stacks it under the title, clamped to two lines.

icon?from PickReactNode

Leading glyph, drawn muted. Use it only when it means something (a kind, a folder). No icon slot renders when omitted.

indexfrom PaletteRowPropsnumber

Position of the row in the whole list, across sections.

onHoverfrom PaletteRowProps(index: number) => void

Called with the row's index when the pointer moves over it.

onRunfrom PaletteRowProps(row: PaletteRowData<T>) => void

Called with the row when it is clicked.

rowfrom PaletteRowPropsPaletteRowData<T>

The row's item and title matches.

style?CSSProperties

Inline styles on the root element, merged after the component's own.

termsfrom PaletteRowPropsnumber

Words in the query: a title match is shown when each reads as one run.

titlefrom PickReactNode

The row's label.

toggle?from Pickboolean

An on/off option: a switch in the trailing slot (use with role="menuitemcheckbox").

topfrom PaletteRowPropsnumber

Offset inside its section.

trailing?from PickReactNode

Content at the row's end, such as a keycap or a meta value. A check or switch from checked or toggle follows it.

ui/src/components/palette/PaletteList.tsx:320

PaletteRowDataInterface#

One ranked result: the item and where its title matched the query (character indices).

TypeScript
interface PaletteRowData<T extends PaletteEntry = PaletteEntry>
PaletteRowData type parameters
NameTypeDefaultDescription
Textends PaletteEntryPaletteEntry
PaletteRowData properties
NameTypeDescription
itemT

The matched item.

titleMatchesreadonly number[]

Indices of the characters of item.title that matched the query. Empty when nothing matched in the title.

ui/src/components/palette/PaletteList.tsx:53

PaletteRowPropsInterface#

Props of one palette row, as passed to renderRow.

TypeScript
interface PaletteRowProps<T extends PaletteEntry = PaletteEntry>
PaletteRowProps type parameters
NameTypeDefaultDescription
Textends PaletteEntryPaletteEntry
PaletteRowProps properties
NameTypeDescription
activeboolean

Whether the cursor is on this row.

choiceboolean

In a picker: a checked row is the current choice.

indexnumber

Position of the row in the whole list, across sections.

onHover(index: number) => void

Called with the row's index when the pointer moves over it.

onRun(row: PaletteRowData<T>) => void

Called with the row when it is clicked.

rowPaletteRowData<T>

The row's item and title matches.

termsnumber

Words in the query: a title match is shown when each reads as one run.

topnumber

Offset inside its section.

ui/src/components/palette/PaletteList.tsx:72

PaletteSectionInterface#

A titled group of ranked rows.

TypeScript
interface PaletteSection<T extends PaletteEntry = PaletteEntry>
PaletteSection type parameters
NameTypeDefaultDescription
Textends PaletteEntryPaletteEntry
PaletteSection properties
NameTypeDescription
rowsreadonly PaletteRowData<T>[]

The section's rows, in order.

titlestring

Heading of the section.

ui/src/components/palette/PaletteList.tsx:64

Types#

PaletteKeysType#

Keycaps for a binding spec (cmd+k); an app with its own binding grammar passes its own.

TypeScript
type PaletteKeys = (spec: string) => ReactNode

ui/src/components/palette/PaletteList.tsx:92