Skip to contentKino
Skip to Content

Calendar

Pick one day, several or a range from a month of days, or a month or a year from twelve. A pill slides to the pick, a range grows along each week, and each month's name opens a popover of months and years.

npx shadcn add https://kinoui.com/r/calendar.json
Share on

Examples

Book the site visit

Kestrel Bakery, 14 Rua das Flores. Weekdays only.
November 2026

Visit on Thursday, 19 November 2026

Default

One day, held as a yyyy-mm-dd string. Weekends and bank holidays are unavailable: struck through, still reachable by the keys, never picked. For a date in a field, the Date picker (opens in a new tab) opens it from a calendar button.

Pick interview days

Lisbon café study. Up to five mornings, from next week.
November 2026

5 of 5 mornings

Multiple

With mode="multiple" each press adds a day or takes it out, and the value is the sorted days. maxDays caps how many: once five are picked, the other days fade until one comes out.

Request time off

Up to 14 days in a row. Weekends and bank holidays can sit inside it.
December 2026, January 2027

21 Dec to 31 Dec · 11 days

Range

With mode="range" the value is [start, end], and null until both ends are picked. months={2} puts two months side by side, and they stack when there isn’t room.

Export card payments

Kestrel Bakery, Lisbon. Up to 92 days at a time.

Pick a preset or two days.

Presets

Hold the value and the month to set them from outside: a vertical Segmented control of presets, which lets go once days are picked by hand.

Your date of birth

For the card reader’s age check.
June 1990

Jump to your year from the month’s name.

Min and max

Days before min and after max fade, and the arrows and the popover’s months and years stop at them. A month’s name is two presses from any year.

Book Casa do Rio

Two guests. Prices are per night.
January 2027

3 nights · £320 · 14 Jan to 17 Jan

Day content

dayContent draws what a day shows in place of its number, such as a price. Screen readers still hear the full date first.

Plan sprint 24

Checkout redesign. Two weeks, from a Monday.
November 2026
44
45
46
47
48
49

Weeks 48 to 49 · 23 Nov to 4 Dec

Week numbers

showWeekNumbers puts each week’s number before it, by ISO 8601 when weeks start on Monday. weekOfYear from the dates lib gives the same number.

Request a demo visit

We bring the card reader to your shop.

Weekdays, from next Monday.

In a form

In a Field, the label names the calendar and the day is sent under the field’s name. With required, sending it empty shows the error and focuses the grid.

Jour de livraison

Café Lumière, 8 rue Oberkampf, Paris.
novembre 2026

Livraison le jeudi 26 novembre 2026

Labels

locale names the months and days, and labels names the calendar’s own buttons, here in French.

Card takings

Kestrel Bakery, by month since it joined Kino.

Showing October 2026

Month

With granularity='month' the Calendar picks a month from its year’s twelve, as its heading’s popover does, and the value is yyyy-mm. The year steps out to twelve years.

Export for your accountant

Every payment and fee in one file, a year at a time.

Year

With granularity='year' it picks a year from twelve, and the value is yyyy. min and max take a year, a month or a day.

MCMove the call with Maya Chen

Quarterly review, 30 minutes.
November 2026

19 Nov · Maya is free 10:00 to 16:00

Cancel a change

Every callback gets Base UI’s change details: details.cancel() keeps the value, and onFocusedChange follows the day with focus, to say why a day can’t be picked.

Installation

npx shadcn@latest add https://kinoui.com/r/calendar.json
Files
lib/reduce-motion.tslib/scroll.tslib/refs.tslib/resize.tslib/swap.tsxlib/popup.tslib/glide.tsxcomponents/kino/tooltip.tsxlib/cut.tsxlib/dates.tscomponents/kino/spinner.tsxcomponents/kino/button.tsxlib/controllable.tslib/field-control.tsxcomponents/kino/popover.tsxlib/run-progress.tslib/highlight.tslib/pill.tscomponents/kino/calendar.tsxlib/calendar-model.tslib/calendar-state.tslib/calendar-grid.tsxlib/calendar-choices.tsx
Packages
@base-ui/reactclass-variance-authority

New to Kino? Installation covers what your project needs first and the @kino namespace.

API reference

Props

PropTypeDefaultDescription
granularity'day''month''year''day'What is picked: a day, a month (yyyy-mm) from a year’s twelve, or a year (yyyy) from twelve. A month or a year is picked one at a time, with value, min, max, deselectable, disabled, readOnly, locale, today, autoFocus, name, form, required, invalid and labels.
mode'single''multiple''range''single'One day, several, or a range from one day to another.
valuestring | nullstring[][string, string] | nullNoneThe picked day, days or range, when you hold the state. A range is null until both ends are picked.
defaultValuestring | nullstring[][string, string] | nullNoneThe value at first, when it holds its own state.
onValueChange(value, details) => voidNoneCalled with the new value. details.reason says why, and details.cancel() keeps the old one.
monthstringNoneThe first month on screen, as yyyy-mm, when you hold it.
defaultMonthstringNoneThe first month at first: the picked day’s, else today’s.
onMonthChange(month, details) => voidNoneCalled when the months turn, by the arrows, the keys or the popover.
minstringNoneThe earliest day that can be picked or focused. With granularity, a year, a month or a day, whose month or year is the first that can be picked.
maxstringNoneThe latest day that can be picked or focused. With granularity, a year, a month or a day.
unavailablestring{ from, to }{ before }{ after }{ weekday: number[] }(date) => booleanan array of themNoneDays that can’t be picked. They show struck through, and the keys still reach them.
allowUnavailablebooleanfalseLets a range hold unavailable days; they still can’t be its ends.
minDaysnumberNoneA range’s fewest days, both ends counted. In multiple mode, the fewest days picked: the last ones can’t come out.
maxDaysnumberNoneA range’s most days, both ends counted. In multiple mode, the most days picked: the rest fade until one comes out.
deselectablebooleanfalseA press on the picked day clears it, in single mode.
monthsnumber1How many months show side by side. They stack when there isn’t room.
pageBy'month''page''month'Whether the arrows move one month, or every month on screen.
disabledbooleanfalseNothing can be focused or picked.
readOnlybooleanfalseFocus and the months still move; the value doesn’t change.
localestringNoneThe language of the month and day names, and the day weeks start on. The browser’s by default.
weekStartsOn0 | 1 | 2 | 3 | 4 | 5 | 6NoneThe day weeks start on, 0 for Sunday. The locale’s by default.
weekdayFormat'narrow''short''long''short'How the names over the days are written.
monthFormat'narrow''short''long''long'How a month’s name is written in its heading.
fixedWeeksbooleantrueSix weeks in every month, so the height never changes.
showOutsideDaysbooleantrueShows the days of the months either side in the first and last week.
todaystringNoneThe day marked as today. The visitor’s own, in timeZone, by default.
timeZonestringNoneThe time zone that decides which day is today.
onRangeStartChange(date, details) => voidNoneCalled with a range’s first day once it is picked, and with null once the range ends or is dropped.
focusedValuestringnullNoneThe day that holds the grid’s focus, when you hold it. Setting it moves the tab stop, turns the months to show it, and moves focus there if the grid has it.
defaultFocusedValuestringnullNoneThe day that holds the grid’s focus at first, and so the month shown first.
autoFocusbooleanfalseFocuses the grid’s tab stop once the months show, as in a date picker that just opened.
showWeekNumbersbooleanfalseShows each week’s number before it: ISO 8601 when weeks start on Monday, else as in the United States, where week 1 holds 1 January.
namestringNoneSends each picked day with a form under this name: one for a day, one each for several, the start then the end for a range. In a Field, its name.
formstringNoneThe id of the form the days go with, when the calendar sits outside it.
requiredbooleanfalseThe form can’t be sent until a day, or a whole range, is picked. In a Field, the error shows and focus goes to the grid.
invalidbooleanfalseDraws a destructive outline, dashed in forced colours. In a Field, its validity decides.
labelsPartial<CalendarLabels>NoneThe names of the calendar’s own buttons, in place of the English ones: previousMonth, nextMonth, chooseMonth(month), chooseYear(year), months, years, previousYear, nextYear, previousYears, nextYears and week(number).
onFocusedChange(date, details) => voidNoneCalled with the day taking focus. From the arrow keys it is asked first, and details.cancel() keeps focus where it is.
dayContent(date, day) => ReactNodeNoneWhat a day shows in place of its number. day says how it is marked: selected, rangeStart, rangeMiddle, rangeEnd, preview, unavailable, disabled, outside, today. Its accessible name stays the full date, followed by what you show.

Data attributes

AttributeOnDescription
data-selecteda day (data-slot="calendar-day")Present while it is picked.
data-range-start, data-range-middle, data-range-enda dayWhere it sits in the range.
data-todaya dayPresent on today.
data-outsidea dayPresent on a day of the month before or after.
data-unavailablea dayPresent on a day unavailable matches.
data-disableda day, CalendarPresent while it can’t be picked, or the whole calendar is disabled.
data-invalidCalendarPresent while it is invalid, or its Field is.
data-week-numbersCalendarPresent while it shows week numbers.
data-modeCalendarsingle, multiple or range.

CSS variables

VariableSet it onDefaultDescription
--calendar-slideCalendar, or anything above it1.5remHow far the months, and the popover’s pages, slide as they turn.
--calendar-zoomCalendar, or anything above it0.92How small the popover’s months get as it steps out to years.

Accessibility

  • Each month is a grid with the keys of the WAI-ARIA date grid (opens in a new tab): the arrows move a day or a week, Home and End to the week’s ends, Page Up and Page Down a month, with Shift a year. Focus turns the months when it leaves them.
  • Name it with aria-label, or put it in a Field, whose label names it and whose description and error describe it; a press on the label focuses the grid. Each month’s grid takes its month’s name, and every day says its full date.
  • Week numbers head their rows, named by labels.week. Every built-in name comes from labels, so the calendar speaks its page’s language.
  • Unavailable days keep focus, so a screen reader hears that they can’t be picked; days outside min and max can’t be reached.
  • The months’ name is a button that opens a Popover (opens in a new tab) of months, with focus on the month shown; Escape closes it back onto the button, and a pick moves focus to the new month’s name.
  • The months on screen are announced as they turn.
  • Today is in bold and aria-current="date"; the pick is a filled pill, with the system highlight in forced colours.
  • When the system asks for less motion, the months, the pill and the band change at once and only fade.