structyl is an open-source, TypeScript-first React component library with 90+ accessible components. It combines WAI-ARIA compliant headless primitives with Tailwind CSS v4 styled wrappers, a runtime theming system, and a first-class DataTable — all in independently-versioned npm packages.

How does structyl differ from shadcn/ui?

structyl ships as actual npm packages (pnpm add @structyl/styled) rather than copy-paste code snippets. It adds a runtime theming system that switches themes without a page reload, a feature-complete DataTable, 24+ React hooks, and 90+ components — significantly more than shadcn/ui out of the box.

How does structyl compare to Radix UI?

structyl builds on the same headless-first philosophy as Radix UI but adds a complete Tailwind-styled layer, runtime theming with CSS variables, dark mode, a DataTable, and chart components. Radix is primitives-only; structyl is a full component library ready to use.

Is structyl compatible with Next.js App Router?

Yes. All structyl components that use React hooks are marked with 'use client'. The library is SSR-safe and fully compatible with Next.js 15 App Router and React Server Components.

Does structyl support dark mode?

Yes. structyl includes a ThemeProvider that supports system, light, and dark modes. Theme switches happen instantly using CSS custom properties — no page reload required and no flash of unstyled content.

How do I install structyl?

Install the main package with: pnpm add @structyl/styled (or npm install @structyl/styled). Then wrap your app in ThemeProvider from @structyl/themes and add Toaster from @structyl/styled to your root layout.

Is structyl free and open source?

Yes. structyl is MIT licensed and completely free. All packages are published to npm under the @structyl scope.

Does structyl support TypeScript?

Yes. structyl is built with TypeScript strict mode throughout. All components export their prop types and the library ships with full type definitions. There is no any usage in the public API.

What styling system does structyl use?

structyl uses Tailwind CSS v4 for styling, tailwind-variants for type-safe variant APIs, and tailwind-merge for class conflict resolution. All colors and design tokens are CSS custom properties that integrate with the runtime theming system.

Does structyl have a DataTable component?

Yes. structyl includes a first-class DataTable in the @structyl/data-table package, built on @tanstack/table-core. It supports sorting, multi-column filtering, pagination, row selection, column resizing, and row virtualization via @tanstack/react-virtual.

Date Time Picker API

View component

The full prop reference for the Date Time Picker component. Pick a date first, then choose the time from one popover with MUI-style props.

Import

tsx

import { DateTimePicker } from '@structyl/styled';

Props

DateTimePicker (default export / Root component)

Styled date-time picker component with integrated label, helper text, and trigger. A wrapper around the primitive Root with added UI styling and convenience props.

Prop	Type	Default
value#	`Date \| null` Controlled date-time value	—
defaultValue#	`Date \| null` Uncontrolled initial date-time value	—
onChange#	`(value: Date \| null, context: PickerChangeContext<DateTimeValidationError>) => void` Fires on any internal state change (view switch, validation, etc.); includes validation error context	—
onValueChange#	`(value: Date \| undefined) => void` Simplified callback; fires when a date/time is committed	—
onAccept#	`(value: Date \| null, context: PickerChangeContext<DateTimeValidationError>) => void` Fires only when a date-time selection is explicitly accepted (e.g., closeOnSelect or accept button)	—
onError#	`(error: DateTimeValidationError \| null, value: Date \| null) => void` Fires when validation state changes; passes current error (null if valid) and the value	—
open#	`boolean` Controlled open state of the popover	—
defaultOpen#	`boolean` Uncontrolled initial open state	—
onOpenChange#	`(open: boolean) => void` Fires when popover open state changes	—
onOpen#	`() => void` Fires when popover opens	—
onClose#	`() => void` Fires when popover closes	—
closeOnSelect#	`boolean` Auto-close popover after a time segment is committed (in time picker mode)	false
disabled#	`boolean` Disable all interaction; disables trigger button and blocks value changes	—
readOnly#	`boolean` Prevent value changes but allow viewing/navigation	—
minDate#	`Date` Minimum selectable date (inclusive); enforced by calendar and validation	—
maxDate#	`Date` Maximum selectable date (inclusive); enforced by calendar and validation	—
minDateTime#	`Date` Minimum selectable date-time; used in validation	—
maxDateTime#	`Date` Maximum selectable date-time; used in validation	—
minTime#	`Date` Minimum selectable time of day; validated against time picker	—
maxTime#	`Date` Maximum selectable time of day; validated against time picker	—
disablePast#	`boolean` Prevent selection of any date/time in the past relative to today	—
disableFuture#	`boolean` Prevent selection of any date/time in the future relative to today	—
disabledDays#	`(date: Date) => boolean` Callback to disable specific dates (deprecated alias for shouldDisableDate)	—
shouldDisableDate#	`(date: Date) => boolean` Callback to disable specific calendar dates; used in validation	—
shouldDisableMonth#	`(date: Date) => boolean` Callback to disable specific months; used in validation and calendar navigation	—
shouldDisableYear#	`(date: Date) => boolean` Callback to disable specific years; used in validation and calendar navigation	—
shouldDisableTime#	`(value: Date, view: TimePickerView) => boolean` Callback to disable specific times based on the current view (hours/minutes/seconds)	—
weekStartsOn#	`number` Day index (0–6) that weeks start on in the calendar; 0 = Sunday	—
locale#	`string` BCP 47 locale tag; affects calendar headers, month names, and time formatting	—
ampm#	`boolean` Use 12-hour format in time picker and Value display (true = AM/PM, false = 24-hour)	—
ampmInClock#	`boolean` If true, display AM/PM selector in clock/time picker (when using time views)	—
autoFocus#	`boolean` Auto-focus the trigger button on mount	—
dayOfWeekFormatter#	`(date: Date) => string` Custom formatter for day-of-week labels in the calendar header	—
desktopModeMediaQuery#	`string` Media query string to determine desktop vs mobile layout	—
disableHighlightToday#	`boolean` Remove visual highlight on today's date in the calendar	—
disableIgnoringDatePartForTimeValidation#	`boolean` Include date part in time validation (normally only time is checked against minTime/maxTime)	—
disableOpenPicker#	`boolean` Disable the trigger button (prevents opening); different from disabled which also blocks internal state changes	—
displayWeekNumber#	`boolean` Show ISO week numbers in the calendar grid	—
fixedWeekNumber#	`number` Force a fixed number of weeks in the calendar grid (e.g. 6 for consistent height)	—
format#	`string \| Intl.DateTimeFormatOptions` Format for the Value display; string uses custom tokens (yyyy, MM, dd, HH, mm, ss, aa), or pass Intl options	—
formatDensity#	`'dense' \| 'spacious'` Compact or spacious date/time field layout in some internal views	—
inputRef#	`React.Ref<HTMLInputElement>` Ref forwarded to internal input element (if any)	—
keepOpenDuringFieldFocus#	`boolean` Keep popover open when field receives focus (normally closes on blur)	—
label#	`React.ReactNode` Label text or node displayed above the trigger; adds * if required=true	—
loading#	`boolean` Show loading state instead of the picker content	—
localeText#	`PickerLocaleText` Object of translated UI strings (e.g. { loading: 'Loading...', ... })	—
minutesStep#	`number` Step size for minute increments in the time picker (default from timeSteps.minutes)	—
monthsPerRow#	`3 \| 4` Number of month columns in month-picker view (3 or 4)	—
name#	`string` HTML name attribute for the trigger button	—
onMonthChange#	`(month: Date) => void` Fires when the user navigates to a different month in the calendar	—
onSelectedSectionsChange#	`(newValue: PickerSelectedSections) => void` Fires when the selected field section changes (for field-based input modes)	—
onViewChange#	`(view: DateTimePickerView) => void` Fires when the internal view switches (day → hours, etc.)	—
onYearChange#	`(year: Date) => void` Fires when the user navigates to a different year in the calendar	—
openTo#	`DateTimePickerView` Initial view to display when popover opens (e.g. 'day', 'month', 'hours')	'day'
orientation#	`'landscape' \| 'portrait'` Layout orientation hint for the picker	—
reduceAnimations#	`boolean` Disable animations and transitions	—
referenceDate#	`Date` Base date used for context (e.g. when navigating time without a selected date)	—
renderLoading#	`() => React.ReactNode` Custom render function for the loading state	—
selectedSections#	`PickerSelectedSections` Controlled selected section in field-based input (day, month, hours, minutes, etc., or 'all')	—
defaultSelectedSections#	`PickerSelectedSections` Uncontrolled initial selected section	—
showDaysOutsideCurrentMonth#	`boolean` Display dates from adjacent months in the calendar grid	—
skipDisabled#	`boolean` In time picker, skip over disabled time values when using arrow keys	—
slotProps#	`PickerSlotProps` Props to pass to internal slot components (advanced)	—
slots#	`PickerSlots` Replace internal components via slot (advanced)	—
sx#	`PickerSx` MUI-style sx prop for styling (advanced)	—
thresholdToRenderTimeInASingleColumn#	`number` Break point (in pixels) below which time picker switches to single-column layout	—
timeSteps#	`TimeSteps` Object { hours?, minutes?, seconds? } defining step size for each time unit	—
timezone#	`string` IANA timezone identifier (if supported by underlying implementation)	—
view#	`DateTimePickerView` Controlled current view (day/month/year/hours/minutes/seconds/meridiem)	—
defaultView#	`DateTimePickerView` Uncontrolled initial view (overrides openTo if not controlled)	—
viewRenderers#	`Partial<Record<DateTimePickerView, DateTimePickerViewRenderer \| null>>` Custom renderers for specific views (advanced); null disables that view	—
views#	`DateTimePickerView[]` Array of enabled views (e.g. ['day', 'hours', 'minutes']); determines available navigation	—
yearsOrder#	`'asc' \| 'desc'` Sort order of year options in year picker	—
yearsPerRow#	`3 \| 4` Number of year columns in year-picker view	—
className#	`string` CSS class applied to the root wrapper div	—
triggerClassName#	`string` CSS class applied to the trigger button (in addition to base button styles)	—
contentClassName#	`string` CSS class applied to the popover content container	—
calendarClassName#	`string` CSS class applied to the calendar grid	—
helperText#	`React.ReactNode` Helper/description text displayed below the trigger; styled as muted	—
placeholder#	`React.ReactNode` Placeholder text when no value is selected (passed to Value component)	—
id#	`string` HTML id for the trigger button (auto-generated if not provided)	—
required#	`boolean` Mark label with * and set aria-required; does not enforce validation	—
error#	`boolean` Set aria-invalid on trigger and apply error styling to helperText	—
showOutsideDays#	`boolean` Alias for showDaysOutsideCurrentMonth (for convenience)	—

DateTimePicker.Trigger

Button that toggles the popover open/closed; pre-styled with calendar icon and default value display

Prop	Type	Default
className#	`string` Additional CSS classes (merged with base button styles)	—
children#	`React.ReactNode` Content; defaults to formatted date-time value if not provided	<DateTimePickerPrimitive.Value />
disabled#	`boolean` Disable the button	—
...other#	`React.HTMLAttributes<HTMLButtonElement>` Standard HTML button attributes (onClick, onFocus, etc.)	—

DateTimePicker.Content

Popover content container; renders calendar + time picker panels with loading state support

Prop	Type	Default
className#	`string` Additional CSS classes (merged with popover base styles)	—
align#	`'start' \| 'center' \| 'end'` Popover alignment relative to trigger	'center'
sideOffset#	`number` Distance (px) between popover and trigger	6
calendarClassName#	`string` CSS classes for the calendar grid inside Content	—
loading#	`boolean` Show loading state instead of date/time pickers	—
showOutsideDays#	`boolean` Pass through to Calendar (show adjacent month dates)	—
showDaysOutsideCurrentMonth#	`boolean` Pass through to Calendar (show adjacent month dates); alias for showOutsideDays	—
withSeconds#	`boolean` Include seconds field in time picker display	—
ampm#	`boolean` Use 12-hour format in time picker	—
maxTime#	`Date` Maximum selectable time; passed to TimePickerPanel	—
minTime#	`Date` Minimum selectable time; passed to TimePickerPanel	—
minutesStep#	`number` Step size for minute increments; passed to TimePickerPanel	—
shouldDisableTime#	`(value: Date, view: TimePickerView) => boolean` Disable specific times; passed to TimePickerPanel	—
skipDisabled#	`boolean` Skip disabled time values in navigation; passed to TimePickerPanel	—
timeSteps#	`TimeSteps` Time step config; passed to TimePickerPanel	—
views#	`DateTimePickerView[]` Enabled views; passed to TimePickerPanel for filtering time views	—
children#	`React.ReactNode` Custom content; if provided, overrides default calendar + time picker layout	—
...other#	`React.HTMLAttributes<HTMLDivElement>` Standard HTML div attributes	—

DateTimePicker.Calendar

Calendar grid for selecting the date part; renders month/year/day views with styled day buttons

Prop	Type	Default
className#	`string` Additional CSS classes (merged with base calendar styles)	—
showOutsideDays#	`boolean` Show dates from adjacent months in the grid	—
showDaysOutsideCurrentMonth#	`boolean` Alias for showOutsideDays	—
locale#	`string` BCP 47 locale (inherited from Root context)	—
...other#	`Omit<CalendarPrimitive.CalendarRootProps, 'selected' \| 'onSelect' \| 'mode'>` Calendar props; selected/onSelect/mode are internally controlled	—

DateTimePicker.DatePanel

Container shown when the date view is active; renders the Calendar inside

Prop	Type	Default
className#	`string` CSS classes	—
...other#	`React.HTMLAttributes<HTMLDivElement>` Standard HTML div attributes	—

DateTimePicker.TimePanel

Container shown when a time view is active; renders time picker controls with date switcher button

Prop	Type	Default
className#	`string` CSS classes	—
children#	`React.ReactNode \| (props: TimePanelRenderProps) => React.ReactNode` Content or render function; receive value, onChange, onAccept, onCancel, view, setView	—
...other#	`React.HTMLAttributes<HTMLDivElement>` Standard HTML div attributes	—

DateTimePicker.DateButton

Button inside TimePanel to switch back to date picker; labeled 'Change date'

Prop	Type	Default
className#	`string` CSS classes (merged with base button styles)	—
...other#	`React.HTMLAttributes<HTMLButtonElement>` Standard HTML button attributes	—

DateTimePicker.Segment

Spinbutton-style segment (hour, minute, second, or AM/PM) in the time picker; keyboard-navigable with arrow keys

Prop	Type	Default
segment#	`'hour' \| 'minute' \| 'second' \| 'period'` Which time segment this control represents	—
className#	`string` CSS classes (merged with base segment styles)	—
...other#	`React.HTMLAttributes<HTMLSpanElement>` Standard HTML span attributes; ArrowUp/ArrowDown adjust the value	—

DateTimePicker.Separator

Visual separator (typically ':') between time segments

Prop	Type	Default
className#	`string` CSS classes	—
children#	`React.ReactNode` Separator character or content	':'
...other#	`React.HTMLAttributes<HTMLSpanElement>` Standard HTML span attributes	—

DateTimePicker.Value

Formatted display of the selected date-time; used as default Trigger/Content children

Prop	Type	Default
format#	`string \| Intl.DateTimeFormatOptions` Format for display; string uses custom tokens (yyyy, MM, dd, HH, mm, ss, aa)	{ dateStyle: 'medium', timeStyle: 'short' }
locale#	`string` BCP 47 locale for Intl.DateTimeFormat	—
placeholder#	`React.ReactNode` Fallback text when no value is selected	'Pick date and time'

DateTimePicker.Loading

Loading state display; shown in Content when loading=true

Prop	Type	Default

DateTimePicker.Root (primitive export)

Unstyled primitive root; provides context and state management for all sub-components. Use this for fully custom layouts.

Prop	Type	Default
children#	`React.ReactNode` Sub-components (Trigger, Content, Calendar, TimePanel, etc.)	—
value#	`Date \| null` Controlled date-time value	—
defaultValue#	`Date \| null` Uncontrolled initial date-time value	—
onChange#	`(value: Date \| null, context: PickerChangeContext<DateTimeValidationError>) => void` Internal state change callback with validation context	—
onValueChange#	`(value: Date \| undefined) => void` Committed value change callback	—
onAccept#	`(value: Date \| null, context: PickerChangeContext<DateTimeValidationError>) => void` Explicit accept (close) callback	—
onError#	`(error: DateTimeValidationError \| null, value: Date \| null) => void` Validation error change callback	—
open#	`boolean` Controlled popover open state	—
defaultOpen#	`boolean` Uncontrolled initial open state	—
onOpenChange#	`(open: boolean) => void` Open state change callback	—
onOpen#	`() => void` Popover opened callback	—
onClose#	`() => void` Popover closed callback	—
closeOnSelect#	`boolean` Auto-close on time segment commit	false
disabled#	`boolean` Disable interactions	—
readOnly#	`boolean` Prevent changes but allow viewing	—
minDate#	`Date` Minimum selectable date	—
maxDate#	`Date` Maximum selectable date	—
minDateTime#	`Date` Minimum selectable date-time	—
maxDateTime#	`Date` Maximum selectable date-time	—
minTime#	`Date` Minimum selectable time of day	—
maxTime#	`Date` Maximum selectable time of day	—
disablePast#	`boolean` Disable past dates/times	—
disableFuture#	`boolean` Disable future dates/times	—
disabledDays#	`(date: Date) => boolean` Deprecated; use shouldDisableDate	—
shouldDisableDate#	`(date: Date) => boolean` Custom date disable logic	—
shouldDisableMonth#	`(date: Date) => boolean` Custom month disable logic	—
shouldDisableYear#	`(date: Date) => boolean` Custom year disable logic	—
shouldDisableTime#	`(value: Date, view: TimePickerView) => boolean` Custom time disable logic	—
weekStartsOn#	`number` Day index (0=Sunday) that weeks start on	—
locale#	`string` BCP 47 locale tag	—
ampm#	`boolean` Use 12-hour format	false
ampmInClock#	`boolean` Show AM/PM selector in time views	—
autoFocus#	`boolean` Auto-focus first interactive element	—
dayOfWeekFormatter#	`(date: Date) => string` Custom day-of-week label formatter	—
desktopModeMediaQuery#	`string` Media query for desktop mode	—
disableHighlightToday#	`boolean` Don't highlight today's date	—
disableIgnoringDatePartForTimeValidation#	`boolean` Include date in time validation	—
disableOpenPicker#	`boolean` Disable opening the picker	—
displayWeekNumber#	`boolean` Show ISO week numbers	—
fixedWeekNumber#	`number` Force fixed number of weeks in calendar	—
format#	`string \| Intl.DateTimeFormatOptions` Value display format	—
formatDensity#	`'dense' \| 'spacious'` Field density	—
inputRef#	`React.Ref<HTMLInputElement>` Ref to internal input (if present)	—
keepOpenDuringFieldFocus#	`boolean` Keep popover open on field focus	—
label#	`React.ReactNode` Label node	—
loading#	`boolean` Show loading state	—
localeText#	`PickerLocaleText` Translated UI strings	—
minutesStep#	`number` Step size for minutes	—
monthsPerRow#	`3 \| 4` Columns in month view	—
name#	`string` HTML name attribute	—
onMonthChange#	`(month: Date) => void` Calendar month navigation	—
onSelectedSectionsChange#	`(newValue: PickerSelectedSections) => void` Selected field section change	—
onViewChange#	`(view: DateTimePickerView) => void` View switch callback	—
onYearChange#	`(year: Date) => void` Calendar year navigation	—
openTo#	`DateTimePickerView` Initial view on open	'day'
orientation#	`'landscape' \| 'portrait'` Layout orientation	—
reduceAnimations#	`boolean` Disable animations	—
referenceDate#	`Date` Base date for context	—
renderLoading#	`() => React.ReactNode` Custom loading render function	—
selectedSections#	`PickerSelectedSections` Controlled selected section	—
defaultSelectedSections#	`PickerSelectedSections` Uncontrolled initial selected section	—
showDaysOutsideCurrentMonth#	`boolean` Show adjacent month dates	—
skipDisabled#	`boolean` Skip disabled times in navigation	—
slotProps#	`PickerSlotProps` Advanced: props for slots	—
slots#	`PickerSlots` Advanced: component slot overrides	—
sx#	`PickerSx` Advanced: MUI-style sx prop	—
thresholdToRenderTimeInASingleColumn#	`number` Responsive breakpoint for time layout	—
timeSteps#	`TimeSteps` Step sizes { hours?, minutes?, seconds? }	—
timezone#	`string` IANA timezone identifier	—
view#	`DateTimePickerView` Controlled current view	—
defaultView#	`DateTimePickerView` Uncontrolled initial view	—
viewRenderers#	`Partial<Record<DateTimePickerView, DateTimePickerViewRenderer \| null>>` Custom view renderers	—
views#	`DateTimePickerView[]` Enabled views array	—
yearsOrder#	`'asc' \| 'desc'` Year sort order	—
yearsPerRow#	`3 \| 4` Columns in year view	—

Source code

If you didn't find what you need here, read the component implementation .