Ranking field

Let people order options with drag, keyboard, and explicit move actions.

Preview

Rank your assistant’s priorities

Cite sources
Use workspace context
Ask before taking action

Installation

Install

npx shadcn@latest add https://ghost-ui.com/r/ranking-field.json

Basic usage

123import { RankingField } from "@/components/ui/ranking-field";

<RankingField name="priorities" options={[{ id: "search", label: "Faster search" }]} defaultValue={["search"]} aria-label="Priorities" />

The id is the stable identity. The value and onValueChange pair contains ids in their current order. When name is supplied, hidden form controls submit those ids in the same order. Use Field for the visible label.

Structures

Examples

Sortable list

Drag any part of a row to move the whole item. Its up and down actions appear on hover or keyboard focus and stay visible on touch devices. Focus a row and use Alt+ArrowUp, Alt+ArrowDown, Alt+Home, or Alt+End for direct moves; Enter starts accessible dragging and Escape cancels it.

Rank your assistant’s priorities

Cite sources
Use workspace context
Ask before taking action

Add and remove custom options

Set allowCustomOptions to show the quiet add action. Blank and duplicate labels are rejected. Custom rows expose a remove action; built-in rows stay protected.

Rank your assistant’s priorities

Cite sources
Use workspace context
Ask before taking action

API reference

RankingField properties
Prop	Type	Default	Description
`form`	`string`		External form ID for hidden ordered inputs.
`addLabel`	`string`	`Add new option`	Caller text for the custom-option action.
`options`	`readonly RankingOption[]`		Stable option identities and labels.
`value`	`readonly string[]`		Controlled option ids in display order.
`defaultValue`	`readonly string[]`		Initial uncontrolled option id order.
`onValueChange`	`(value: readonly string[]) => void`		Called after a drag, keyboard move, or move action.
`name`	`string`		Name for hidden inputs. FormData receives ids in current order.
`allowCustomOptions`	`boolean`		Shows add, cancel, duplicate validation, and custom remove actions.
`onOptionsChange`	`(options: readonly RankingOption[]) => void`		Receives the option list after a custom option is added or removed.
`disabled`	`boolean`		Disables all interaction.
`required`	`boolean`		Announces that at least one option is required when the list is empty.

The component composes canonical Button, IconButton, ButtonGroup, and Input owners. Dragging is progressive enhancement: the move buttons and documented keyboard commands provide the same result without pointer drag support. An offscreen polite status announces the resulting position or custom-option change.

Native div attributes and a div ref are supported on the root. Labels and business validation belong to the caller.