Inputs

Dropdown

Custom select / action menu with a pill trigger and keyboard nav.

An accessible listbox dropdown with a soft pill trigger, an optional leading icon, and a floating panel that lights options in the accent on hover or arrow-key focus. Works as an action menu (fixed label) or a value select (shows the chosen option). Full keyboard support — arrows, Home / End, type-ahead, Enter, Escape — and themeable via CSS variables. Powers every single-select field in Form.

Installation

Add the package. A custom, accessible listbox dropdown — keyboard-driven, themeable, with a soft pill trigger and a floating panel. No separate stylesheet.

pnpm add @roy-ui/ui

Import

import { Dropdown } from '@roy-ui/ui';

// or just this component:
import { Dropdown } from '@roy-ui/ui/dropdown';

Usage

Two modes from one component. Give it a fixed label and it's an action menu (the trigger text never changes — selecting fires onChange). Omit the label and it's a select: the trigger shows the chosen option, or a placeholder. Open it and use Arrow keys, Home / End, type-ahead, Enter to choose, Escape to close.

Action menu

A fixed label plus a leading icon. Selecting an option fires onChange (e.g. to kick off an export) without changing the trigger. Open it and hover or arrow through — the active option lights up in the accent.

tsx

<Dropdown
  label="Export as"
  icon={<DownloadIcon />}
  aria-label="Export as"
  options={[
    { label: 'Export as .pdf', value: 'pdf' },
    { label: 'Export as .csv', value: 'csv' },
    { label: 'Export as .xlsx', value: 'xlsx' },
  ]}
  onChange={(format) => exportFile(format)}
/>

Select

No label, so the trigger shows the selected option (or the placeholder). fullWidth stretches it to fill a form field. The chosen option keeps a check.

tsx

const [role, setRole] = useState('');

<Dropdown
  fullWidth
  placeholder="Choose a role"
  value={role}
  onChange={setRole}
  options={[
    { label: 'Engineer', value: 'eng' },
    { label: 'Designer', value: 'design' },
    { label: 'Product', value: 'pm' },
  ]}
/>

In a Form

The schema Form uses this Dropdown for every single-select field — set type: "select" with options and it renders here automatically (multi-select stays a native list). See the Form docs for the full schema.

Schema field

const fields = [
  { name: 'role', type: 'select', label: 'Role',
    placeholder: 'Choose a role',
    options: [
      { label: 'Engineer', value: 'eng' },
      { label: 'Designer', value: 'design' },
    ],
    rules: { required: true } },
];

<Form fields={fields} onSubmit={save} />

Theming

Every surface is a CSS variable. The accent is purple by default to match the reference — override --royui-dropdown-accent (and its tint) to re-brand it.

Variables

.royui-dropdown {
  --royui-dropdown-accent: #6d4afe;        /* active / selected text */
  --royui-dropdown-accent-bg: #f1ecfe;     /* active option background */
  --royui-dropdown-surface: #ffffff;       /* trigger + panel */
  --royui-dropdown-icon-bg: #1e2233;       /* leading icon circle */
  --royui-dropdown-icon-fg: #ffffff;
}

Props

options is the only required prop. Controlled with value + onChange, or uncontrolled with defaultValue.

Prop	Type	Default	Description
`options`	`DropdownOption[]`	`—`	Required. { label, value, disabled? } per row.
`value`	`string`	`—`	Controlled selected value.
`defaultValue`	`string`	`—`	Uncontrolled initial value.
`onChange`	`(value: string) => void`	`—`	Fires when an option is chosen.
`label`	`ReactNode`	`—`	Fixed trigger text (menu mode). Omit for select mode.
`placeholder`	`ReactNode`	`—`	Trigger text in select mode when nothing is selected.
`icon`	`ReactNode`	`—`	Leading glyph in the trigger circle.
`fullWidth`	`boolean`	`false`	Stretch the trigger to fill its container.
`align`	`'left' \| 'right'`	`'left'`	Which edge the panel aligns to.
`invalid`	`boolean`	`false`	Recolour the trigger border for an invalid field.
`disabled`	`boolean`	`false`	Dim and block interaction.
`theme`	`'light' \| 'dark' \| 'auto'`	`'auto'`	Follow the system or force a side.

Dropdown

Custom select / action menu with a pill trigger and keyboard nav.

Usage

<Dropdown label="Export as" icon={<DownloadIcon />} aria-label="Export as" options={[ { label: 'Export as .pdf', value: 'pdf' }, { label: 'Export as .csv', value: 'csv' }, { label: 'Export as .xlsx', value: 'xlsx' }, ]} onChange={(format) => exportFile(format)} />

const [role, setRole] = useState(''); <Dropdown fullWidth placeholder="Choose a role" value={role} onChange={setRole} options={[ { label: 'Engineer', value: 'eng' }, { label: 'Designer', value: 'design' }, { label: 'Product', value: 'pm' }, ]} />

const fields = [ { name: 'role', type: 'select', label: 'Role', placeholder: 'Choose a role', options: [ { label: 'Engineer', value: 'eng' }, { label: 'Designer', value: 'design' }, ], rules: { required: true } }, ]; <Form fields={fields} onSubmit={save} />

.royui-dropdown { --royui-dropdown-accent: #6d4afe; /* active / selected text */ --royui-dropdown-accent-bg: #f1ecfe; /* active option background */ --royui-dropdown-surface: #ffffff; /* trigger + panel */ --royui-dropdown-icon-bg: #1e2233; /* leading icon circle */ --royui-dropdown-icon-fg: #ffffff; }

Prop

Type

Default

Description

options

DropdownOption[]

—

Required. { label, value, disabled? } per row.

value

string

—

Controlled selected value.

defaultValue

string

—

Uncontrolled initial value.

onChange

(value: string) => void

—

Fires when an option is chosen.

label

ReactNode

—

Fixed trigger text (menu mode). Omit for select mode.

placeholder

ReactNode

—

Trigger text in select mode when nothing is selected.

icon

ReactNode

—

Leading glyph in the trigger circle.

fullWidth

boolean

false

Stretch the trigger to fill its container.

align

'left' | 'right'

'left'

Which edge the panel aligns to.

invalid

boolean

false

Recolour the trigger border for an invalid field.

disabled

boolean

false

Dim and block interaction.

theme

'light' | 'dark' | 'auto'

'auto'

Follow the system or force a side.