Dates@knitui/dates

YearLevel

YearLevel is the month-grid calendar level: a CalendarHeader (year label + prev/next/level controls) atop a MonthsList 4×3 grid. A year zooms out to a decade, so the level label stays interactive (onLevelClick). The prev/next controls auto-disable at the minDate/maxDate bounds, and the label honours yearLabelFormat + the DatesProvider locale. Use the styles prop to tweak the header parts and the grid.

WebiOSAndroid7 style slots22 own props7 examples

Stories Source Tests Open in Storybook

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

Playground

Loading playground…

sizeWidth/font of the header controls and month cells.

yearA date within the displayed year (`YYYY-MM-DD`).

withNextRender the next control.

true

withPreviousRender the previous control.

true

fullWidthTake the full width of the container.

false

Playground

<YearLevel
  year="2024-01-01"
  size="md"
  withNext
  withPrevious
  fullWidth={false}
  previousLabel="Previous year"
  nextLabel="Next year"
  levelControlAriaLabel="Year"
/>

Examples

Default

The default year level (header + the month grid).

Loading example…

DefaultSource Storybook

Custom Label

A function yearLabelFormat overrides the default YYYY label.

Loading example…

Custom LabelSource Storybook

Bounded

Bounded — minDate/maxDate auto-disable the prev/next controls at the edges.

Loading example…

BoundedSource Storybook

Full Width

Full-width level — the header and grid fill the container.

Loading example…

Full WidthSource Storybook

Styled Parts

Per-slot styles sugar — round the header controls and recolor the label.

Loading example…

Styled PartsSource Storybook

Sizes

Every size from the shared xxs…xxl cell-metrics ladder.

Loading example…

SizesSource Storybook

Props

Prop	Type	Default	Description
`year` required	`string`	`2024-01-01`	A date within the displayed year (`YYYY-MM-DD`).
`disabled` system	`boolean \| undefined`	—	—
`fullWidth` system	`boolean \| undefined`	`false`	Take the full width of the container.
`getMonthControlProps`	`((date: DateStringValue) => Partial<PickerControlProps>) \| undefined`	—	Passes props down to each month `PickerControl`, keyed by date (wins over `styles.control`).
`hasNextLevel`	`boolean \| undefined`	`true`	Whether the level button can zoom out to the next level.
`headerControlsOrder`	`CalendarHeaderControlName[] \| undefined`	`['previous', 'level', 'next']`	Order in which the controls are rendered.
`levelControlAriaLabel`	`string \| undefined`	`Year`	Level control `aria-label`.
`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.
`monthsListFormat`	`string \| undefined`	`'MMM'`	dayjs format for the month labels.
`nextDisabled`	`boolean \| undefined`	`false`	Disables the next control.
`nextIcon`	`ReactNode`	—	Replace the next-button icon.
`nextLabel`	`string \| undefined`	`Next year`	Next button `aria-label`.
`onLevelClick`	`(() => void) \| undefined`	—	Called when the level button is pressed.
`onNext`	`(() => void) \| undefined`	—	Called when the next button is pressed.
`onPrevious`	`(() => void) \| undefined`	—	Called when the previous button is pressed.
`previousDisabled`	`boolean \| undefined`	`false`	Disables the previous control.
`previousIcon`	`ReactNode`	—	Replace the previous-button icon.
`previousLabel`	`string \| undefined`	`Previous year`	Previous button `aria-label`.
`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 header controls and month cells.
`styles` system	`SlotStyles<YearLevelStyles> \| undefined`	—	Per-slot style sugar — props spread onto the matching part (header + grid).
`theme` system	`ThemeName \| null \| undefined`	—	Applies a theme to this element
`withCellSpacing`	`boolean \| undefined`	`true`	Separate controls/rows with spacing.
`withNext`	`boolean \| undefined`	`true`	Render the next control.
`withPrevious`	`boolean \| undefined`	`true`	Render the previous control.
`yearLabelFormat`	`DateLabelFormat \| undefined`	`'YYYY'`	dayjs format for the year label, or a function returning it.

Style slots

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

Slot	Targets
`header`	Props for the header bar (`CalendarHeader` `root` slot).
`headerControl`	Props for each header prev/next control (`CalendarHeader` `control` slot).
`headerIcon`	Props for the header chevron glyphs (`CalendarHeader` `icon` slot).
`headerLevel`	Props for the header level (label) control (`CalendarHeader` `level` slot).
`headerLevelLabel`	Props for the header level label text (`CalendarHeader` `levelLabel` slot).
`months`	Props for the `MonthsList` grid root (`.List`) — style props only; `year` is owned.
`root`	Props for the level root column (`.Frame`).

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.