API

The parts of tambour and the props they take.

Anatomy#

Import Tambour and put the parts together.

import { Tambour } from "tambour/react";

<Tambour.Root>
	<Tambour.Wheel items={items} />
</Tambour.Root>;

Components#

Both parts forward a ref and any other props to their div.

Root#

Holds the value of every wheel and draws the center band.

PropTypeDefault
valueV[]-
defaultValueV[]-
onValueChange(value: V[]) => void-
onValueCommit(value: V[]) => void-
disabledbooleanfalse
itemHeightnumber36
reducedMotionbooleanThe user's setting

onValueChange runs as a wheel crosses each item. onValueCommit runs when a change made by the user comes to rest.

itemHeight is in pixels, and everything else scales with it.

Wheel#

One column of items. It has to be inside a Root.

PropTypeDefault
itemsT[]Required
loopbooleanfalse
disabledbooleanfalse
getValue(item: T) => unknownitem.value, or the item
getLabel(item: T) => stringitem.label, or the value
renderItem(item: T, index: number) => ReactNode-
indexnumberIts order in the Root

See Items for what a wheel can hold.

Wheel positions#

A wheel's position is its order among the Root's wheels, looking through fragments and plain elements. Separators don't count.

A wheel inside your own component can't be seen from the Root, so give it an index. The same goes for a wheel whose parent is a server component. Pass index to every wheel if you pass it to one.

Keyboard#

A focused wheel takes these keys.

KeyAction
ArrowUp, ArrowDownMoves one item
PageUp, PageDownMoves five items
Home, EndMoves to the first or last item, unless it loops

Accessibility#

Each wheel is a spinbutton that speaks its item's label, and the Root is a group. Give each of them an aria-label, since it's what a screen reader announces.

Good to know#