--- package: "@svenskaspel/ui" version: "4.4.0" document_type: "component-documentation" source: "@svenskaspel/ui/docs/calendar.md" canonical_url: "/components/date-picker" usage_source: "src/app/(docs)/components/date-picker/page.mdx" --- # Date Picker Date Picker allows for selecting a date or a range of dates from a calendar view. ![Date picker](/images/components/date-picker/date-picker-date-picker-231-1084-0.webp) *** ## Usage Use the Date picker to provide the user an intuitive way to pick a singular, or a range of dates. ### Calendar The Calendar and the Date picker consist of two separate components, where the former typically is triggered by the latter. Typically the Date picker will be used to reveal the calendar and allow the user to pick a date, or dates, however the calendar can be displayed on its own or be triggered by another component. ![Calendar](/images/components/date-picker/date-picker-calendar-231-1182-0.webp) The Calendar displayed standalone. ### Select a default value when appropriate For many situations a pre-selected date may aid the user in completing a task. ![Select a default value when appropriate – 1](/images/components/date-picker/default-value-do.webp) > **Do:** Select a default value that reflects the most common use case. ![Select a default value when appropriate – 2](/images/components/date-picker/default-value-dont.webp) > **Don't:** Don’t present the Date picker blank if a default selection can aid the user. *** ## Formatting ### Anatomy The Date picker component is made up of a Calendar for picking dates, and a field similar to the Input component for displaying the currently selected date(s), or a placeholder if no selection has been made. ![Anatomy](/images/components/date-picker/date-picker-anatomy-231-1160-0.webp) 1. Label 2. Placeholder / Input text 3. Calendar icon 4. Container 5. Help text #### Label Describes the expected input, e.g. “Select your birth date”. Keep the label text short, clear and concise, and aim to make it no longer than a few words. #### Placeholder text The place holder text can provide a hint regarding the expected format. Keep in mind that once the user starts interacting with the Date picker, the placeholder text is replaced with the user input. As such it is important to make sure important information is available in the label or help text. #### Input text The selected date provided by the user, or pre-selected by the system. #### Help text The help text is an optional field that can be used to provide additional guidance or contextual information about the expected input. Consider using the help text when extra clarification is needed for the user to complete their task. #### Error text Error text is displayed when validation fails and is used to inform the user that the selected date is incorrect, and ideally what needs to be corrected in order to achieve success. ### States – Date picker The Date picker displays interaction states similar to input fields and the select component. The Date picker displays interaction states similar to input fields and the select component. #### Default ![States – Date picker – 1](/images/components/date-picker/date-picker-states-date-picker-268-1012-0.webp) The default state prior to user interaction, displaying a placeholder text. #### Hover ![States – Date picker – 2](/images/components/date-picker/date-picker-states-date-picker-268-1012-1.webp) On desktop devices the Date picker will react to a hovering cursor. #### Focus ![States – Date picker – 3](/images/components/date-picker/date-picker-focus.webp) The Date picker is in focus and is available for accepting input. #### Filled ![Filled – 1](/images/components/date-picker/date-picker-filled-268-1028-0.webp) The Date picker with a selected date, either selected by the user, or a default selection by the system. #### Error ![Error](/images/components/date-picker/date-picker-filled-268-1028-1.webp) An incorrect date is selected. Attempt to prevent the user from making erroneous selections. #### Disabled ![Disabled](/images/components/date-picker/date-picker-filled-268-1028-2.webp) The Date picker is not available for interaction. #### Calendar ![Calendar](/images/components/date-picker/date-picker-calendar-340-1195-0.webp) 1. Container 2. Title 3. Month Navigator 4. Weekday 5. Date cell – default 6. Date cell – selected 7. Date cell – current date 8. Date cell – range 9. Date cell – disabled ### Title A title indicating the currently selected month and year. ### Month navigator Buttons allowing the user to navigate months backward and forward. ### Weekday Indicates the weekday of the dates in the column below. ### Date cells A calendar date that can be selected, mark the current date or be part of a range. ### States – Calendar The individual date elements have a set of interaction states indicating their current status. A single date can be in its default state, selected, part of a selected range, the current date, or disabled. #### Default ![States – Calendar – 1](/images/components/date-picker/date-picker-states-calendar-231-1106-0.webp) In its default state is not currently selected or the current date, and is available for selection. #### Hover ![States – Calendar – 2](/images/components/date-picker/date-picker-states-calendar-231-1106-1.webp) On desktop devices a date element will respond to a hovering cursor. #### Range ![States – Calendar – 3](/images/components/date-picker/date-picker-states-calendar-231-1106-2.webp) Indicates that the date is part of a selected range. #### Current ![Current – 1](/images/components/date-picker/date-picker-current-231-1144-0.webp) The current date is indicated with an outline. #### Selected ![Selected](/images/components/date-picker/date-picker-current-231-1144-1.webp) A selected date – either a singular date, the start or end of a range. #### Disabled ![Disabled](/images/components/date-picker/date-picker-current-231-1144-2.webp) A date currently unavailable for selection. ### Use consistent date formatting ![Use consistent date formatting – 1](/images/components/date-picker/date-picker-use-consistent-date-formatting-1-505-1166-0.webp) > **Do:** Format the displayed date according to Svenska Spel guidelines ![Use consistent date formatting – 2](/images/components/date-picker/date-format-dont.webp) > **Don't:** Don’t present the date with inconsistent or incorrect formatting. *** ## Behaviour Interacting with the Date Picker allows the user to enter a date manually. Clicking the calendar icon displays the Calendar, allowing the user to select a date or dates. ### Single date When the user interacts with a date the calendar closes and the Date picker displays the selected date. Interacting with the Date picker again will open the calendar with the selected date indicated. ![Single date](/images/components/date-picker/date-picker-single-date-265-982-0.webp) ### Range selection The range selector allows for picking multiple dates and requires interaction with a button for confirming selection. ![Range selection](/images/components/date-picker/date-picker-range-selection-265-1052-0.webp) *** ## Modify The date picker is available with a solid base and as an outline variant. When using the outline variant, be mindful of the background surface to ensure accessibility is maintained. --- # Readme / API # Calendar The `Calendar` component provides a reusable date selection interface for React applications. It is built using TypeScript and leverages the `react-day-picker` library (version 10) for date handling and rendering. ## Importing ```typescript import { Calendar } from '@svenskaspel/ui/react/calendar'; ``` ## Usage ### Single Date Selection ```typescriptreact import * as React from 'react'; import { Calendar } from '@svenskaspel/ui/react/calendar'; const MyComponent = () => { const [selectedDate, setSelectedDate] = React.useState(new Date()); return ; }; ``` ### Date Range Selection ```typescriptreact import * as React from 'react'; import { Calendar } from '@svenskaspel/ui/react/calendar'; import type { DateRange } from 'react-day-picker'; const MyComponent = () => { const [selectedRange, setSelectedRange] = React.useState(undefined); return ; }; ``` ### Multiple Date Selection ```typescriptreact import * as React from 'react'; import { Calendar } from '@svenskaspel/ui/react/calendar'; const MyComponent = () => { const [selectedDates, setSelectedDates] = React.useState([]); return ( ); }; ``` ### Disabling Dates ```typescriptreact import * as React from 'react'; import { Calendar } from '@svenskaspel/ui/react/calendar'; const MyComponent = () => { const [selectedDate, setSelectedDate] = React.useState(undefined); const disabledDates = [ new Date(2025, 5, 10), // June 10, 2025 { from: new Date(2025, 5, 15), to: new Date(2025, 5, 20) }, // Range ]; return ( ); }; ``` ## API ### Calendar Props The `Calendar` component accepts all props from `react-day-picker`'s `DayPicker` component, plus some additional customization options. Use the version 10 styling keys when passing `classNames` or `styles`. For example, use `month_grid` for the calendar table; the deprecated `table` key is no longer supported. See the [DayPicker v10 upgrade guide](https://daypicker.dev/upgrading) for removed props and aliases. **Key Props:** | Option | Type | Description | | ----------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------- | | `mode` | `'single' \| 'multiple' \| 'range' \| undefined` | Determines the selection mode. Omitted by default; set a mode to enable selection. | | `selected` | `Date \| Date[] \| DateRange \| undefined` | The currently selected date(s). Type depends on `mode`. | | `onSelect` | `function` | Callback when selection changes. Signature depends on `mode`. | | `disabled` | `Matcher \| Matcher[]` | Dates that cannot be selected. Can be a `Date`, `DateRange`, or function. | | `locale` | `Locale` | The locale for formatting (from `react-day-picker/locale`). Defaults to Swedish (`sv`). | | `showOutsideDays` | `boolean` | Whether to show days from previous/next months. Defaults to `true`. | | `numberOfMonths` | `number` | Number of months to display. Defaults to `1`. | | `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | Day of week to start on (0 = Sunday). Defaults to `1` (Monday). | | `buttonVariant` | `ButtonVariant` | The variant to use for navigation buttons. Defaults to `'ghost'`. | | `className` | `string` | Additional CSS classes for the root container. | | `classNames` | `Partial` | Custom CSS classes for internal elements. | **Selection Modes:** - **`'single'`**: Allows selecting a single date. - `selected: Date | undefined` - `onSelect: (date: Date | undefined) => void` - Additional props: `required: boolean` - **`'multiple'`**: Allows selecting multiple dates. - `selected: Date[] | undefined` - `onSelect: (dates: Date[] | undefined) => void` - Additional props: `min: number`, `max: number` - **`'range'`**: Allows selecting a date range. - `selected: DateRange | undefined` (object with `from` and `to` Date properties) - `onSelect: (range: DateRange | undefined) => void` - Additional props: `min: number`, `max: number` **Navigation & Display:** | Option | Type | Description | | ------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------- | | `month` | `Date` | The month to display. | | `defaultMonth` | `Date` | The month to display initially if `month` is not set. | | `startMonth` / `endMonth` | `Date` | First and last months available for navigation. | | `hidden` | `Matcher \| Matcher[]` | Hide matching dates; use before/after matchers for date limits. | | `pagedNavigation` | `boolean` | Navigate by the number of months displayed. | | `captionLayout` | `'label' \| 'dropdown' \| 'dropdown-months' \| 'dropdown-years'` | Layout of the month caption. Defaults to `'label'`. | ## Styling The `Calendar` component is pre-styled using Tailwind CSS utility classes. You can customize its appearance in several ways: 1. **Root Container**: Pass a `className` prop to add custom styles to the calendar container. 2. **Internal Elements**: Use the `classNames` prop to customize specific parts of the calendar: ```typescriptreact ``` ### Range Selection Styling When using `mode="range"`, the calendar automatically applies special styling: - Selected range dates receive a gray background (`bg-surface-elevated-selected`) - Range start and end dates display circular indicators with the secondary color - Range middle dates have square backgrounds - The calendar has a rounded border; no range-specific shadow is added ### Button Variants Navigation buttons use the `buttonVariants` from the Button component. You can customize the variant: ```typescriptreact ``` ## Localization The Calendar component supports localization via the `locale` prop, which accepts a `Locale` object from `react-day-picker/locale`. The default locale is Swedish (`sv`). ```typescriptreact import { Calendar } from '@svenskaspel/ui/react/calendar'; import { enUS } from 'react-day-picker/locale'; ; ``` ### Week Start Day By default, weeks start on Monday. You can change this with `weekStartsOn`: ```typescriptreact ``` ## Accessibility The Calendar component is built on `react-day-picker`, which follows WAI-ARIA best practices: - Full keyboard navigation support (arrow keys, Page Up/Down, Home/End) - Screen reader friendly with proper ARIA labels - Focus management with visible focus indicators - Semantic HTML structure with proper `role` attributes ### Keyboard Navigation - **Arrow keys**: Navigate between days - **Page Up/Down**: Navigate between months - **Home/End**: Jump to start/end of week - **Enter/Space**: Select the focused date - **Tab**: Move between interactive elements ## Advanced Usage ### Restricting Date Range Limit the selectable date range: ```typescriptreact ``` ### Multiple Months Display multiple months side by side: ```typescriptreact ``` ### Custom Formatters Customize how dates are formatted: ```typescriptreact date.toLocaleString('sv-SE', { month: 'long' }), formatCaption: (date) => `Custom ${date.getFullYear()}`, }} /> ``` ## Additional Information - [react-day-picker Documentation](https://daypicker.dev/) - [date-fns Documentation](https://date-fns.org/)