Ranking Field

ProNew

Order a list by preference: drag a handle with the pointer, or pick up with Space and move with the arrow keys, or use the move buttons; changes are announced, and an optional top-N cut-off marks what counts.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/ranking-field

Usage

Props

Prop	Type	Description
`items`	`{ id, label, description? }[]`	The things to rank.
`value` / `onChange`	`string[]`	Ids in rank order. Missing ids are appended.
`topN`	`number`	Only the first N count; a divider marks the cut-off.
`legend`, `description`	`ReactNode`	Question and hint.
`disabled`	`boolean`

Accessibility

Three equivalent ways to reorder: pointer drag on the grip, the keyboard pick-up pattern, and plain Up and Down buttons. The buttons exist because the grab pattern has to be learned and some assistive technologies handle it poorly.
The grip is a button with aria-pressed while picked up and aria-roledescription="sortable item"; its name includes the position ("position 2 of 5"). Space or Enter picks up and drops; Arrow Up and Arrow Down move; Escape cancels and restores the order; blur drops.
Every move is announced in an assertive live region with the item name and its new position. Focus stays on the item's grip after a move.
The grip uses touch-action: none so dragging does not scroll the page; the pointer capture ends on release or cancel.
The cut-off is a separator with a text label, not only a line.

Testing

The component ships with a Testing Library test (ranking-field.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/ranking-field

Usage

Props

Prop	Type	Description
`items`	`{ id, label, description? }[]`	The things to rank.
`value` / `onChange`	`string[]`	Ids in rank order. Missing ids are appended.
`topN`	`number`	Only the first N count; a divider marks the cut-off.
`legend`, `description`	`ReactNode`	Question and hint.
`disabled`	`boolean`

Accessibility

Three equivalent ways to reorder: pointer drag on the grip, the keyboard pick-up pattern, and plain Up and Down buttons. The buttons exist because the grab pattern has to be learned and some assistive technologies handle it poorly.
The grip is a button with aria-pressed while picked up and aria-roledescription="sortable item"; its name includes the position ("position 2 of 5"). Space or Enter picks up and drops; Arrow Up and Arrow Down move; Escape cancels and restores the order; blur drops.
Every move is announced in an assertive live region with the item name and its new position. Focus stays on the item's grip after a move.
The grip uses touch-action: none so dragging does not scroll the page; the pointer capture ends on release or cancel.
The cut-off is a separator with a text label, not only a line.

Testing

The component ships with a Testing Library test (ranking-field.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.