Dates@knitui/dates

YearsList

YearsList is the year selection grid — a ragged 3/3/3/1 grid of PickerControls built from Box rows/cells (never an HTML <table>), so it renders on web and native. Per-cell sizing/colour/interaction live in the PickerControl leaf; YearsList lays out the rows/cells, shares size via context, and offers a per-year getYearControlProps passthrough plus per-slot styles sugar. Accent comes from the active Tamagui theme.

WebiOSAndroid4 style slots7 own props8 examples

Stories Source Tests Open in Storybook

import { YearsList } from "@knitui/dates";

Playground

Loading playground…

sizeWidth/font of the controls.

withCellSpacingSeparate controls/rows with spacing.

true

fullWidthStretch the grid to its container width.

false

yearsListFormatdayjs format for the year labels.

Playground

<YearsList
  decade="2024-01-01"
  size="md"
  withCellSpacing
  fullWidth={false}
  yearsListFormat="YYYY"
/>

Examples

Default

Default year grid with a selected year.

Loading example…

DefaultSource Storybook

Custom Format

Custom label format — two-digit years.

Loading example…

Custom FormatSource Storybook

Bounded

Bounded — years outside [minDate, maxDate] are disabled.

Loading example…

BoundedSource Storybook

Full Width

Full-width grid stretched to its container's width (controls share each row equally).

Loading example…

Full WidthSource Storybook

Full Width Filled

fullWidth fills BOTH axes — in a fixed-height box the rows distribute the height and the controls grow taller.

Loading example…

Full Width FilledSource Storybook

Styled Slots

Per-slot styles sugar — recolour every control via the control slot.

Loading example…

Styled SlotsSource Storybook

Sizes

Every size token.

Loading example…

SizesSource Storybook

Props

Prop	Type	Default	Description
`decade` required	`string`	`2024-01-01`	Decade for which the years list is displayed, any date within it (`YYYY-MM-DD`).
`disabled` system	`boolean \| undefined`	—
`fullWidth` system	`boolean \| undefined`	`false`	Stretch the grid to its container width.
`getYearControlProps`	`((date: DateStringValue) => Partial<PickerControlProps>) \| undefined`	—	Passes props down to each year `PickerControl`, keyed by date (wins over `styles.control`).
`locale`	`string \| undefined`	—	dayjs locale; falls back to the value defined in `DatesProvider`.
`maxDate`	`string \| Date \| undefined`	—	Maximum possible date in `YYYY-MM-DD` format or a `Date` object.
`minDate`	`string \| Date \| undefined`	—	Minimum possible date in `YYYY-MM-DD` format or a `Date` object.
`shadow` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined`	—
`size` system	`CalendarSize \| undefined` xxs · xs · sm · md · lg · xl · xxl	`'md'`	Width/font of the controls.
`styles` system	`SlotStyles<YearsListStyles> \| undefined`	—	Per-slot style sugar — props spread onto the matching styled part. Lives on `YearsListProps` (not the inherited `YearsListSettings`) so the `styles` shape does not flow up the shared Calendar settings chain and collide with sibling components' own `styles` props.
`theme` system	`ThemeName \| null \| undefined`	—	Applies a theme to this element
`withCellSpacing`	`boolean \| undefined`	`true`	Separate controls/rows with spacing.
`yearsListFormat`	`string \| undefined`	`'YYYY'`	dayjs format for the year labels.

Style slots

Every part of YearsList can be styled through the styles prop. Explicit props on the component always win over slot styles.

Slot	Usage
`cell`	`styles={{ cell: { … } }}`
`control`	`styles={{ control: { … } }}`
`root`	`styles={{ root: { … } }}`
`row`	`styles={{ row: { … } }}`

Accessibility & DOM props (2)

Prop	Type
`key`	`Key \| null \| undefined`
`ref`	`Ref<TamaguiElement> \| undefined`

Plus 498 inherited style props from Box — the full Tamagui/React Native style surface, including token shorthands like p, mx, bg and c. See Tokens for the scales they accept, or the full list.