Date Selector
Allows users to quickly choose single dates or time ranges using interactive timeline scrubbers and preset shortcut buttons.
33.9 KB
•Updated on August 21, 2026
Installation
Bash
pnpm dlx shadcn@latest add @spaceui/components-spaceui-date-selectorUsage
Code
import * as React from 'react'
import { DateSelector, type DateSelectorValue } from '@/components/spaceui/date-selector'
export default function SpaceUI() {
const [value, setValue] = React.useState<DateSelectorValue | undefined>()
return <DateSelector value={value} onChange={setValue} label="Due date" />
}Examples
With Popover
With Dialog
With i18n Support
API Reference
DateSelector
The main component for selecting dates and time periods.
| Prop | Type | Default | Description |
|---|---|---|---|
value | DateSelectorValue | - | The current value of the selector. |
onChange | (value: DateSelectorValue) => void | - | Callback fired when the value changes. |
allowRange | boolean | true | Whether to allow selecting date ranges (using "between" operator). |
periodTypes | DateSelectorPeriodType[] | - | List of available period types (day, month, etc.). |
defaultPeriodType | DateSelectorPeriodType | day | The initial period type. |
defaultFilterType | DateSelectorFilterType | is | The initial filter operator. |
presetMode | DateSelectorFilterType | - | If set, locks the selector to this specific filter mode. |
showInput | boolean | true | Whether to show the text input field above the selector. |
showTwoMonths | boolean | true | Whether to show two months in the calendar view (desktop only). |
label | string | - | Optional label to display above the filter toggle. |
yearRange | number | 10 | The number of years to show in the year/month/quarter list. |
baseYear | number | new Date().getFullYear() | The reference year for the year selection list. |
minYear | number | 2015 | The minimum selectable year. |
maxYear | number | 2026 | The maximum selectable year. |
i18n | Partial<DateSelectorI18nConfig> | - | Custom labels and operators for internationalization. |
inputHint | string | - | Optional hint text to display in the input field when empty and focused. |
dayDateFormat | string | MM/dd/yyyy | The format used to display single days. |
className | string | - | Additional CSS classes for the container. |
Interfaces
DateSelectorValue
The structure of the value returned by the onChange callback.
| Property | Type | Description |
|---|---|---|
period | DateSelectorPeriodType | The selected period type (day, month, quarter, half-year, year). |
operator | DateSelectorFilterType | The selected operator (is, before, after, between). |
startDate | Date | The selected start date (for day period). |
endDate | Date | The selected end date (for day period range). |
year | number | The selected year. |
month | number | The selected month (0-11). |
quarter | number | The selected quarter (0-3). |
halfYear | number | The selected half-year (0-1). |
rangeStart | { year: number; value: number } | The start of a period range. |
rangeEnd | { year: number; value: number } | The end of a period range. |
Keep in mind
- MIT License: Free and open-source for personal and commercial use. Feel free to copy, tweak, and adapt the components to match your exact needs.
- Credits & Inspiration: Some components on this site are inspired by or recreated from great ideas across the web. I'm not here to take credit; just to learn, experiment, and push interface craft further.
- Reach out & Claims: If an attribution was missed, or if you have any inquiry or claim, feel free to reach out directly on X to @adrielzimbril. I'll be glad to update or resolve it right away.