Dates@knitui/dates

MonthsList

MonthsList is the month selection grid — a 4×3 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; MonthsList lays out the rows/cells, shares size via context, and offers a per-month getMonthControlProps 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 { MonthsList } 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

monthsListFormatdayjs format for the month labels.

Playground

<MonthsList
  year="2026-06-15"
  size="md"
  withCellSpacing
  fullWidth={false}
  monthsListFormat="MMM"
/>

Examples

Default

Default month grid with a selected month.

Loading example…

DefaultSource Storybook

Custom Format

Custom label format — full month names.

Loading example…

Custom FormatSource Storybook

Bounded

Bounded — months 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
`year` required	`string`	`2026-06-15`	Year for which the months 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.
`getMonthControlProps`	`((date: DateStringValue) => Partial<PickerControlProps>) \| undefined`	—	Passes props down to each month `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.
`monthsListFormat`	`string \| undefined`	`'MMM'`	dayjs format for the month labels.
`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<MonthsListStyles> \| undefined`	—	Per-slot style sugar — props spread onto the matching styled part. Lives on `MonthsListProps` (not the inherited `MonthsListSettings`) 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.

Style slots

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

Slot	Targets
`cell`	Props for each month-cell wrapper (`.Cell`).
`control`	Props for each control inside a cell (`.Control` — the `PickerControl` leaf).
`root`	Props for the grid container (`.Frame`).
`row`	Props for each month row (`.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.