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.

Select API

View component

The full prop reference for the Select component. Displays a list of options for the user to pick from, triggered by a button.

Import

tsx

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

Props

Select.Root

Root wrapper that manages the select state and provides context to child components

Prop	Type	Default
children#	`React.ReactNode` Child components (Trigger, Content, etc.)	—
value#	`string` Controlled selected value	—
defaultValue#	`string` Uncontrolled initial value	—
onValueChange#	`(value: string) => void` Called when selected value changes	—
open#	`boolean` Controlled open state of dropdown	—
defaultOpen#	`boolean` Uncontrolled initial open state	false
onOpenChange#	`(open: boolean) => void` Called when dropdown opens or closes	—
dir#	`'ltr' \| 'rtl'` Text direction for RTL support	—
name#	`string` Name attribute for form submission (creates hidden select element)	—
autoComplete#	`string` HTML autoComplete attribute for the hidden select	—
disabled#	`boolean` Disables all interactions with the select	—
required#	`boolean` Marks the field as required for form validation	false
searchable#	`boolean` Enables search/filter functionality in dropdown	false
searchValue#	`string` Controlled search input value	—
defaultSearchValue#	`string` Uncontrolled initial search value	''
onSearchValueChange#	`(value: string) => void` Called when search input changes	—
filterOption#	`(option: SelectFilterOption, searchValue: string) => boolean` Custom filter function for search (defaults to textValue/value matching)	—
onCreateOption#	`(value: string) => void` Called when user creates a new option via search	—
createOptionLabel#	`React.ReactNode \| ((value: string) => React.ReactNode)` Label shown for create option in dropdown	—
resetSearchOnClose#	`boolean` Clear search value when dropdown closes	true

Select.Trigger

Button that opens/closes the dropdown, styled with icon and state

Prop	Type	Default
asChild#	`boolean` Merge props onto child element instead of creating a button	—
className#	`string` CSS class for custom styling (styled layer adds default classes)	—
disabled#	`boolean` Disable this specific trigger (merged with Root.disabled)	—
onClick#	`(event: React.MouseEvent) => void` Custom click handler (composed with open handler)	—
onPointerDown#	`(event: React.PointerEvent) => void` Custom pointer down handler (composed with open handler)	—
onKeyDown#	`(event: React.KeyboardEvent) => void` Custom key down handler (composed with open handler)	—
children#	`React.ReactNode` Content inside trigger (typically Value + Icon)	—

Select.Value

Displays the selected value or placeholder in the trigger

Prop	Type	Default
placeholder#	`React.ReactNode` Text/node shown when no value is selected	—
asChild#	`boolean` Merge props onto child element instead of creating a span	—
className#	`string` CSS class for custom styling	—
children#	`React.ReactNode` Custom render function for selected value (overrides value text)	—

Select.Icon

Dropdown chevron icon displayed in the trigger

Prop	Type	Default
asChild#	`boolean` Merge props onto child element instead of creating a span	—
className#	`string` CSS class for custom styling (default: '▼')	—
children#	`React.ReactNode` Custom icon content	'▼'

Select.SearchInput

Search input field in the dropdown (only renders when searchable=true)

Prop	Type	Default
asChild#	`boolean` Merge props onto child element instead of creating an input	—
className#	`string` CSS class for custom styling	—
placeholder#	`string` Placeholder text for search input	—
onChange#	`(event: React.ChangeEvent<HTMLInputElement>) => void` Custom change handler (composed with search update)	—
onKeyDown#	`(event: React.KeyboardEvent) => void` Custom key down handler (composed with navigation/create)	—

Select.Portal

Portals the dropdown content to document body (for z-index/overflow)

Prop	Type	Default
children#	`React.ReactNode` Child elements to portal	—
container#	`Element \| DocumentFragment \| null` Target DOM element for portal (defaults to document.body)	—
forceMount#	`boolean` Always render content in DOM (even when closed)	—

Select.Content

Dropdown content container with positioning and animations (styled wrapper)

Prop	Type	Default
asChild#	`boolean` Merge props onto child element instead of creating a div	—
className#	`string` CSS class for custom styling	—
position#	`'item-aligned' \| 'popper'` Positioning strategy	'popper'
side#	`'top' \| 'right' \| 'bottom' \| 'left'` Preferred side to place content relative to trigger	'bottom'
sideOffset#	`number` Distance from trigger to content	4
align#	`'start' \| 'center' \| 'end'` Alignment relative to trigger	'start'
alignOffset#	`number` Offset alignment by this distance	—
avoidCollisions#	`boolean` Auto-flip side when hitting viewport boundaries	true
collisionBoundary#	`Element \| Element[] \| null` Elements to check for collisions	—
collisionPadding#	`number` Padding from collision boundary	—
strategy#	`'fixed' \| 'absolute'` CSS positioning strategy	—
sticky#	`'partial' \| 'always'` Keep content sticky when scrolling	—
hideWhenDetached#	`boolean` Hide content when trigger is hidden	—
updatePositionStrategy#	`'always' \| 'optimized'` How often to recalculate position	—
onCloseAutoFocus#	`(event: Event) => void` Called when content closes (focus returns to trigger)	—
onEscapeKeyDown#	`(event: KeyboardEvent) => void` Called when Escape key pressed	—
onPointerDownOutside#	`(event: Event) => void` Called when pointer down outside content	—
options#	`SelectOption[]` Array of options (styled wrapper convenience, renders with Options component)	—
optionHeight#	`number` Height of each option for virtualization	36
optionOverscan#	`number` Number of options to render outside visible area	6
optionEmptyMessage#	`React.ReactNode` Message shown when no options match search	—
renderOption#	`(option: SelectOption) => React.ReactNode` Custom render function for each option	—
showCreateItem#	`boolean` Show 'Create' option when onCreateOption is provided	true
container#	`Element \| DocumentFragment \| null` Portal container target	—
forceMount#	`boolean` Force mount content in DOM	—
children#	`React.ReactNode` Custom child content (alternative to options prop)	—

Select.Item

Individual selectable option in the dropdown

Prop	Type	Default
value#	`string` Unique value for this option (required)	—
disabled#	`boolean` Prevent selection of this option	—
textValue#	`string` Text used for search filtering (extracted from children if not provided)	—
asChild#	`boolean` Merge props onto child element instead of creating a div	—
className#	`string` CSS class for custom styling	—
children#	`React.ReactNode` Item label/content (typically ItemText and ItemIndicator)	—
onClick#	`(event: React.MouseEvent) => void` Custom click handler (composed with selection logic)	—
onPointerMove#	`(event: React.PointerEvent) => void` Custom pointer move handler (composed with focus)	—
onPointerLeave#	`(event: React.PointerEvent) => void` Custom pointer leave handler	—
onKeyDown#	`(event: React.KeyboardEvent) => void` Custom key down handler (composed with arrow/enter navigation)	—
onFocus#	`(event: React.FocusEvent) => void` Custom focus handler	—

Select.ItemText

Text content of a select item (displays in both item and value)

Prop	Type	Default
asChild#	`boolean` Merge props onto child element instead of creating a span	—
className#	`string` CSS class for custom styling	—
children#	`React.ReactNode` Item text content	—

Select.ItemIndicator

Checkmark or custom indicator shown when item is selected

Prop	Type	Default
asChild#	`boolean` Merge props onto child element instead of creating a span	—
className#	`string` CSS class for custom styling	—
children#	`React.ReactNode` Custom indicator content	—

Select.CreateItem

Option to create a new item when searchable and onCreateOption provided

Prop	Type	Default
value#	`string` Override the created value (defaults to search input)	—
asChild#	`boolean` Merge props onto child element instead of creating a div	—
className#	`string` CSS class for custom styling	—
children#	`React.ReactNode \| ((value: string) => React.ReactNode)` Custom label or function that receives search value	—
onClick#	`(event: React.MouseEvent) => void` Custom click handler (composed with create logic)	—
onPointerMove#	`(event: React.PointerEvent) => void` Custom pointer move handler	—
onPointerLeave#	`(event: React.PointerEvent) => void` Custom pointer leave handler	—
onKeyDown#	`(event: React.KeyboardEvent) => void` Custom key down handler (composed with navigation/create)	—

Select.Options

Virtualized options container with automatic rendering of SelectOption array

Prop	Type	Default
options#	`SelectOption[]` Array of options to render (required)	—
itemHeight#	`number` Height of each option for virtualization	36
overscan#	`number` Number of items to render outside visible area	6
visibleItemCount#	`number` Number of items visible at once for fallback height	8
emptyMessage#	`React.ReactNode` Message when no options match filter	'No options found.'
itemClassName#	`string` CSS class added to each rendered Item	—
itemTextClassName#	`string` CSS class added to each ItemText	—
itemIndicatorClassName#	`string` CSS class added to each ItemIndicator	—
renderOption#	`(option: SelectOption) => React.ReactNode` Custom render function for option label	—
renderItemIndicator#	`(option: SelectOption) => React.ReactNode` Custom render function for selection indicator	—
asChild#	`boolean` Merge props onto child element	—
className#	`string` CSS class for custom styling	—
children#	`React.ReactNode` Rendered option items (auto-populated from options prop)	—

Select.Group

Logical grouping of select items with optional label

Prop	Type	Default
asChild#	`boolean` Merge props onto child element instead of creating a div	—
className#	`string` CSS class for custom styling	—
children#	`React.ReactNode` Group contents (Label, Items, etc.)	—

Select.Label

Label/header for a select group

Prop	Type	Default
asChild#	`boolean` Merge props onto child element instead of creating a div	—
className#	`string` CSS class for custom styling	—
children#	`React.ReactNode` Label text	—

Select.Separator

Visual divider between groups or items

Prop	Type	Default
asChild#	`boolean` Merge props onto child element instead of creating a div	—
className#	`string` CSS class for custom styling	—
children#	`React.ReactNode` Separator content	—

Select.Viewport

Scrollable container for options (used with Content)

Prop	Type	Default
asChild#	`boolean` Merge props onto child element instead of creating a div	—
className#	`string` CSS class for custom styling	—
children#	`React.ReactNode` Options/content to display	—

Keyboard interactions

Adheres to the WAI-ARIA design pattern .

Key	Description
`Space / Enter`	Opens the select / selects the focused item.
`ArrowDown / ArrowUp`	Moves focus between options.
`Esc`	Closes the select.

Source code

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