# AvatarGroup (/docs/components/avatar-group) import { AvatarGroupBasicDemo } from "../../../src/components/avatar-group-basic-demo"; import { AvatarGroupOverflowDemo } from "../../../src/components/avatar-group-overflow-demo"; import { AvatarGroupSizesDemo } from "../../../src/components/avatar-group-sizes-demo"; ## Overview The AvatarGroup component displays a collection of avatars in an overlapping layout with smart overflow handling. When the number of avatars exceeds the maximum, it shows a "+N" indicator with a popover containing all overflow avatars. Each avatar includes an individual tooltip on hover. ## Import ```tsx import { AvatarGroup } from "@px-ui/core"; ``` ## Usage ```tsx const avatars = [ { name: "Alice Johnson", imgSrc: "https://github.com/shadcn.png", size: "40px" }, { name: "Bob Smith", imgSrc: null, size: "40px" }, { name: "Carol Williams", imgSrc: null, size: "40px" }, { name: "David Brown", imgSrc: null, size: "40px" }, ]; ``` ## Examples ### With Overflow When there are more avatars than the `max` prop allows, the component shows a "+N" indicator. Hover over it to see all overflow avatars in a popover. ```tsx const avatars = [ { name: "Alice Johnson", imgSrc: null, size: "40px", variant: "rounded" }, { name: "Bob Smith", imgSrc: null, size: "40px", variant: "rounded" }, // ... 6 more avatars ]; ``` ### Different Sizes The AvatarGroup automatically adapts to the size specified in the avatar props, maintaining proper overlap and scaling. ```tsx const smallAvatars = [ { name: "Alice Johnson", imgSrc: null, size: "32px", variant: "rounded" }, { name: "Bob Smith", imgSrc: null, size: "32px", variant: "rounded" }, // ... ]; const largeAvatars = [ { name: "Alice Johnson", imgSrc: null, size: "48px", variant: "rounded" }, { name: "Bob Smith", imgSrc: null, size: "48px", variant: "rounded" }, // ... ]; ``` ## API Reference ### AvatarGroup A component that displays a collection of overlapping avatars with overflow handling. | Prop | Type | Default | Description | | ----------- | -------------------------------------- | ------- | ----------------------------------------------------------------------------------------- | | `avatars` | `Array>` | - | Array of avatar configurations. Each item should be a valid Avatar component props object | | `max` | `number` | `4` | Maximum number of avatars to display before showing overflow indicator | | `className` | `string` | - | Additional CSS classes for the container | ### Avatar Props Each object in the `avatars` array accepts all Avatar component props: | Prop | Type | Description | | --------- | ------------------------ | ------------------------------------------- | | `name` | `string` | User name for initials fallback and tooltip | | `imgSrc` | `string \| null` | Image source URL | | `size` | `` `${number}px` `` | Size of the avatar (e.g., "40px", "48px") | | `variant` | `"squared" \| "rounded"` | Visual style variant | **Features:** * Avatars overlap by 25% of their width for a compact layout * Each avatar has a white ring border to separate them visually * Z-index stacking ensures proper depth (first avatar appears on top) * Overflow avatars are shown in a scrollable popover on hover * Individual tooltips show each user's name on hover # Avatar (/docs/components/avatar) import { AvatarBasicDemo } from "../../../src/components/avatar-basic-demo"; import { AvatarVariantsDemo } from "../../../src/components/avatar-variants-demo"; import { AvatarInitialsDemo } from "../../../src/components/avatar-initials-demo"; import { AvatarSizesDemo } from "../../../src/components/avatar-sizes-demo"; import { AvatarWithBadgeDemo } from "../../../src/components/avatar-with-badge-demo"; ## Overview The Avatar component displays user profile pictures with automatic fallback to colored initials when images are unavailable. It includes smart features like deterministic color generation, built-in tooltips, and support for status badge overlays. ## Import ```tsx import { Avatar } from "@px-ui/core"; ``` ## Usage ```tsx ``` ## Examples ### Variants The Avatar component supports two visual variants: `squared` with rounded corners, and `rounded` for fully circular avatars. ```tsx ``` ### Initials Fallback When no image is provided, the Avatar automatically displays initials with a color generated from the user's name. Each unique name consistently receives the same color. ```tsx ``` ### Sizes Avatars can be customized to any size using the `size` prop with pixel values. ```tsx ``` ### With Status Badge Wrap the Avatar in a relative container to position status badges or indicators. ```tsx
``` ## API Reference ### Avatar Displays a user avatar with image or initials fallback. | Prop | Type | Default | Description | | ------------- | ----------------------------- | ----------- | -------------------------------------------------------------- | | `imgSrc` | `string \| null \| undefined` | - | Image source URL. Supports `/SIZE/` pattern for dynamic sizing | | `name` | `string \| null \| undefined` | - | User name for initials fallback and tooltip display | | `variant` | `"squared" \| "rounded"` | `"squared"` | Visual style variant | | `size` | `` `${number}px` `` | `"100px"` | Size of the avatar in pixels | | `className` | `string` | - | Additional CSS classes | | `hideTooltip` | `boolean` | `false` | Disable the name tooltip on hover | **Inherited Props:** Inherits all props from [Base UI Avatar.Root](https://base-ui.com/react/components/avatar#root). # BlockCheckboxGroup (/docs/components/block-checkbox-group) import { BlockCheckboxGroupBasicDemo } from "../../../src/components/block-checkbox-group-basic-demo"; import { BlockCheckboxGroupMultipleDemo } from "../../../src/components/block-checkbox-group-multiple-demo"; import { BlockCheckboxGroupWithIconsDemo } from "../../../src/components/block-checkbox-group-with-icons-demo"; ## Overview The BlockCheckboxGroup component provides large, card-style checkboxes ideal for presenting options with titles and descriptions. It supports multiple selections with visual feedback through hover effects, border changes, and smooth transitions. ## Import ```tsx import { BlockCheckboxGroup } from "@px-ui/core"; ``` ## Usage ```tsx Email Notifications Receive notifications via email when there's activity on your account SMS Notifications Get text messages for important updates and alerts ``` ## Examples ### Multiple Selections Users can select multiple options simultaneously. ```tsx React A JavaScript library for building user interfaces {/* More items... */} ``` ### With Icons Add icons to headers for better visual recognition. ```tsx Pro Plan For growing teams. Includes advanced features and priority support. ``` ## Anatomy Components that make up BlockCheckboxGroup: ### BlockCheckboxGroup.Group The container component that manages checkbox group state. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI CheckboxGroup](https://base-ui.com/react/components/checkbox-group) including `value`, `defaultValue`, `onValueChange`, `disabled`, etc. *** ### BlockCheckboxGroup.Item Large card-style checkbox item with hover and checked state styling. **Custom Props:** | Prop | Type | Default | Description | | ----------- | --------- | ------- | ------------------------------------------------ | | `invalid` | `boolean` | `false` | When true, applies error styling with red shadow | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from the Checkbox component including `value`, `disabled`, etc. **Features:** * Minimum height of 155px for consistent card size * Hover border effect when not disabled * Primary border when checked * Red shadow when invalid * Reduced opacity when disabled *** ### BlockCheckboxGroup.Header Container for header content (typically icon and title). **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | *** ### BlockCheckboxGroup.Title Title text for the checkbox option. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | *** ### BlockCheckboxGroup.Description Descriptive text explaining the checkbox option. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | ## API Reference See the Anatomy section above for detailed prop information for each component. # BlockRadioGroup (/docs/components/block-radio-group) import { BlockRadioGroupBasicDemo } from "../../../src/components/block-radio-group-basic-demo"; import { BlockRadioGroupWithIconsDemo } from "../../../src/components/block-radio-group-with-icons-demo"; import { BlockRadioGroupSelectionDemo } from "../../../src/components/block-radio-group-selection-demo"; ## Overview The BlockRadioGroup component provides large, card-style radio buttons ideal for presenting mutually exclusive options with titles and descriptions. It supports single selection with visual feedback through hover effects, border changes, and smooth transitions. ## Import ```tsx import { BlockRadioGroup } from "@px-ui/core"; ``` ## Usage ```tsx Standard Shipping Delivery in 5-7 business days · Free Express Shipping Delivery in 2-3 business days · $9.99 ``` ## Examples ### With Icons Add icons to headers for better visual recognition and hierarchy. ```tsx Pro Plan $29/month · Advanced features and priority support ``` ### Payment Selection A common use case for block-style radio groups is payment method selection. ```tsx Credit Card Pay securely with your credit or debit card {/* More options... */} ``` ## Anatomy Components that make up BlockRadioGroup: ### BlockRadioGroup.Group The container component that manages radio group state for single selection. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI RadioGroup](https://base-ui.com/react/components/radio-group) including `value`, `defaultValue`, `onValueChange`, `disabled`, etc. *** ### BlockRadioGroup.Item Large card-style radio button with hover and checked state styling. **Custom Props:** | Prop | Type | Default | Description | | ----------- | --------- | ------- | ------------------------------------------------ | | `invalid` | `boolean` | `false` | When true, applies error styling with red shadow | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from RadioGroup.Item including `value`, `disabled`, etc. **Features:** * Minimum height of 155px for consistent card size * Hover border effect when not disabled * Primary border when checked * Red shadow when invalid * Reduced opacity when disabled *** ### BlockRadioGroup.Header Container for header content (typically icon and title). **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | *** ### BlockRadioGroup.Title Title text for the radio option. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | *** ### BlockRadioGroup.Description Descriptive text explaining the radio option. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | ## API Reference See the Anatomy section above for detailed prop information for each component. # Breadcrumbs (/docs/components/breadcrumbs) import { BreadcrumbsBasicDemo } from "../../../src/components/breadcrumbs-basic-demo"; import { BreadcrumbsWithIconsDemo } from "../../../src/components/breadcrumbs-with-icons-demo"; import { BreadcrumbsLongDemo } from "../../../src/components/breadcrumbs-long-demo"; ## Overview The Breadcrumbs component provides hierarchical navigation that shows the user's current location and allows them to navigate back through parent pages. It includes proper ARIA attributes for accessibility and supports icons, custom rendering, and responsive layouts. ## Import ```tsx import { Breadcrumbs } from "@px-ui/core"; ``` ## Usage ```tsx Home Documentation Components ``` ## Examples ### With Icons Add icons to breadcrumb links for better visual recognition. ```tsx Home ``` ### Long Navigation Paths The breadcrumbs component automatically wraps on smaller screens thanks to its responsive flex layout. ```tsx Home {/* Multiple levels... */} Current Page ``` ## Anatomy Components that make up Breadcrumbs: ### Breadcrumbs.Breadcrumb The root navigation wrapper with proper ARIA labeling. **Inherited Props:** Inherits all props from native HTML `nav` element. *** ### Breadcrumbs.BreadcrumbList The ordered list container for breadcrumb items. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from native HTML `ol` element. *** ### Breadcrumbs.BreadcrumbItem Individual list item wrapper for each breadcrumb. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from native HTML `li` element. *** ### Breadcrumbs.BreadcrumbLink Clickable link to navigate to a parent page. **Custom Props:** | Prop | Type | Default | Description | | ----------- | ---------- | ------- | --------------------------------------------------------------------------------- | | `className` | `string` | - | Additional CSS classes | | `render` | `function` | - | Custom render function for using custom link components (e.g., React Router Link) | **Inherited Props:** Inherits all props from native HTML `a` element including `href`. *** ### Breadcrumbs.BreadcrumbPage The current page indicator (non-clickable). **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from native HTML `span` element. *** ### Breadcrumbs.BreadcrumbSeparator Visual separator between breadcrumb items (chevron icon). **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from native HTML `li` element. ## API Reference See the Anatomy section above for detailed prop information for each component. # Button (/docs/components/button) import { ButtonBasicDemo } from "../../../src/components/button-basic-demo"; import { ButtonVariantsDemo } from "../../../src/components/button-variants-demo"; import { ButtonSizesDemo } from "../../../src/components/button-sizes-demo"; import { ButtonWithIconsDemo } from "../../../src/components/button-with-icons-demo"; import { ButtonDisabledDemo } from "../../../src/components/button-disabled-demo"; ## Overview The Button component provides clickable elements with consistent styling across your application. It supports seven visual variants for different use cases, five size options including icon-specific sizes, and automatic styling for icons and disabled states. ## Import ```tsx import { Button } from "@px-ui/core"; ``` ## Usage ```tsx ``` ## Examples ### Variants The Button component supports seven visual variants to match different contexts and hierarchies in your interface. ```tsx ``` ### Sizes Buttons can be rendered in five different sizes, including specialized sizes for icon-only buttons. ```tsx ``` ### With Icons Buttons automatically handle icon spacing and sizing when SVG icons are included as children. ```tsx ``` ### Disabled State All button variants include distinct disabled state styling. ```tsx ``` ## API Reference ### Button A styled button component with variant and size customization. | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------------------------------------------ | ----------- | ----------------------------------------------------------------- | | `variant` | `"default" \| "primary" \| "destructive" \| "outline" \| "primary-outline" \| "ghost" \| "link"` | `"default"` | Visual style variant of the button | | `size` | `"default" \| "sm" \| "lg" \| "icon-sm" \| "icon"` | `"default"` | Size of the button. Use `icon-sm` or `icon` for icon-only buttons | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from native HTML `button` element including `onClick`, `disabled`, `type`, etc. # Calendar (/docs/components/calendar) import { CalendarBasicDemo } from "../../../src/components/calendar-basic-demo"; import { CalendarRangeDemo } from "../../../src/components/calendar-range-demo"; import { CalendarMultipleDemo } from "../../../src/components/calendar-multiple-demo"; import { CalendarDropdownDemo } from "../../../src/components/calendar-dropdown-demo"; ## Overview The Calendar component provides a visual interface for date selection. Built on react-day-picker, it supports single date selection, date ranges, multiple dates, and includes features like month/year dropdowns and keyboard navigation. ## Import ```tsx import { Calendar } from "@px-ui/core"; ``` ## Usage ```tsx const [selected, setSelected] = useState(new Date()); ``` ## Examples ### Range Selection Allow users to select a date range with visual highlighting between start and end dates. ```tsx const [selected, setSelected] = useState({ from: new Date(), to: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), }); ``` ### Multiple Selection Enable selection of multiple individual dates. ```tsx const [selected, setSelected] = useState([ new Date(), new Date(Date.now() + 2 * 24 * 60 * 60 * 1000), ]); ``` ### With Dropdowns Use dropdown menus for month and year selection to quickly navigate to distant dates. ```tsx ``` ## API Reference ### Calendar The main calendar component for date selection. | Prop | Type | Default | Description | | ----------------- | ----------------------------------- | ---------- | ------------------------------------------------------- | | `mode` | `"single" \| "multiple" \| "range"` | `"single"` | Selection mode for the calendar | | `selected` | `Date \| Date[] \| DateRange` | - | Currently selected date(s) | | `onSelect` | `function` | - | Callback when date selection changes | | `disabled` | `Date \| Date[] \| function` | - | Dates that cannot be selected | | `showOutsideDays` | `boolean` | `true` | Show days from adjacent months | | `captionLayout` | `"label" \| "dropdown"` | `"label"` | Layout for month/year caption | | `fromYear` | `number` | - | Starting year for dropdown (when using dropdown layout) | | `toYear` | `number` | - | Ending year for dropdown (when using dropdown layout) | | `showWeekNumber` | `boolean` | `false` | Display week numbers | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [react-day-picker DayPicker](https://react-day-picker.js.org/api/interfaces/DayPickerProps) *** ## Common Patterns ### Disabling Dates Disable specific dates or date ranges: ```tsx // Disable past dates // Disable specific dates // Disable with custom function date.getDay() === 0 || date.getDay() === 6} /> ``` ### Default Month Control which month is initially displayed: ```tsx ``` ### Multiple Months Display multiple months side by side: ```tsx ``` # Checkbox (/docs/components/checkbox) import { CheckboxBasicDemo } from "../../../src/components/checkbox-basic-demo"; import { CheckboxSizesDemo } from "../../../src/components/checkbox-sizes-demo"; import { CheckboxIndeterminateDemo } from "../../../src/components/checkbox-indeterminate-demo"; import { CheckboxDisabledDemo } from "../../../src/components/checkbox-disabled-demo"; ## Overview The Checkbox component provides a binary selection control that allows users to toggle between checked and unchecked states. It includes support for an indeterminate state for representing partial selections, multiple sizes, and full keyboard accessibility. ## Import ```tsx import { Checkbox } from "@px-ui/core"; ``` ## Usage ```tsx
``` ## Examples ### Sizes The Checkbox component supports three size variants to match different interface densities. ```tsx ``` ### Indeterminate State The indeterminate state is useful for representing partial selections, such as when a parent checkbox controls multiple child checkboxes and only some are selected. ```tsx ``` ### Disabled State Checkboxes can be disabled in any state: unchecked, checked, or indeterminate. ```tsx ``` ## API Reference ### Checkbox A binary selection control component with customizable size and indeterminate state support. | Prop | Type | Default | Description | | --------------- | --------------------------- | ----------- | -------------------------------------------------------------- | | `variant` | `"default"` | `"default"` | Visual style variant | | `size` | `"default" \| "sm" \| "lg"` | `"default"` | Size of the checkbox | | `indeterminate` | `boolean` | `false` | When true, displays a minus icon to indicate partial selection | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Checkbox.Root](https://base-ui.com/react/components/checkbox#root) including `checked`, `defaultChecked`, `onCheckedChange`, `disabled`, `required`, etc. # Collapsible (/docs/components/collapsible) import { CollapsibleBasicDemo } from "../../../src/components/collapsible-basic-demo"; import { CollapsibleWithIconDemo } from "../../../src/components/collapsible-with-icon-demo"; import { CollapsibleNestedDemo } from "../../../src/components/collapsible-nested-demo"; import { CollapsibleControlledDemo } from "../../../src/components/collapsible-controlled-demo"; ## Overview The Collapsible component provides an expandable/collapsible container for content. It includes smooth height-based animations and a toggle icon that rotates to indicate the open/closed state. ## Import ```tsx import { Collapsible } from "@px-ui/core"; ``` ## Usage ```tsx Show more details

This is the collapsible content that can be expanded or collapsed. Click the trigger above to toggle visibility.

``` ## Examples ### With Custom Trigger Use a custom styled trigger with the toggle icon to create an interactive header. ```tsx Advanced Settings

Configure advanced options here.

 ``` ### Nested Collapsibles Collapsible components can be nested to create hierarchical content structures. ```tsx Parent Section
Child Section

Nested content here.
``` ### Controlled Use the `open` and `onOpenChange` props to control the collapsible state externally. ```tsx const [open, setOpen] = React.useState(false); Click here or use button above

This collapsible is controlled externally.

 ``` ## Anatomy Components that make up `Collapsible`: ### `Collapsible.Root` The root container that manages the collapsible state and coordinates all child components. **Custom Props:** | Prop | Type | Default | Description | | -------------- | ------------------------- | ------- | --------------------------------- | | `className` | `string` | - | Additional CSS classes | | `open` | `boolean` | - | Controlled open state | | `defaultOpen` | `boolean` | `false` | Default open state (uncontrolled) | | `onOpenChange` | `(open: boolean) => void` | - | Callback when open state changes | **Inherited Props:** Inherits all props from [Base UI Collapsible.Root](https://base-ui.com/react/components/collapsible#root) *** ### `Collapsible.Trigger` The interactive element that toggles the collapsible open/closed state. Should be used with `group` class to enable icon rotation. **Inherited Props:** Inherits all props from [Base UI Collapsible.Trigger](https://base-ui.com/react/components/collapsible#trigger) *** ### `Collapsible.Panel` The container for content that expands and collapses with a smooth animation. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Collapsible.Panel](https://base-ui.com/react/components/collapsible#panel) *** ### `Collapsible.ToggleIcon` A chevron icon that rotates 90 degrees when the collapsible is open. Must be used inside a trigger with `group` class. **Note:** This component has no props. It uses the parent trigger's `group-data-[panel-open]` state to rotate. *** ## API Reference See the [Anatomy](#anatomy) section above for detailed component props. # Combobox Field (/docs/components/combobox-field) import ComboboxFieldBasicDemo from "../../../src/components/combobox-field-basic-demo.tsx"; import ComboboxFieldMultipleDemo from "../../../src/components/combobox-field-multiple-demo.tsx"; import ComboboxFieldAsyncDemo from "../../../src/components/combobox-field-async-demo.tsx"; import ComboboxFieldSizesDemo from "../../../src/components/combobox-field-sizes-demo.tsx"; import ComboboxFieldSearchPopupDemo from "../../../src/components/combobox-field-search-popup-demo.tsx"; ## Overview ComboboxField is a simplified wrapper around the Combobox component that streamlines searchable selection use cases. It automatically handles item rendering, label detection, search functionality, and supports both single and multiple selections with async data loading. For more complex scenarios requiring custom sub-component composition, use the full Combobox component from `@px-ui/core`. ## Import ```tsx import { ComboboxField } from "@px-ui/forms"; ``` ## Usage ```tsx import { ComboboxField } from "@px-ui/forms"; import { useState } from "react"; export default function Example() { const [value, setValue] = useState(null); const items = [ { id: "apple", label: "Apple" }, { id: "banana", label: "Banana" }, { id: "orange", label: "Orange" }, { id: "mango", label: "Mango" }, { id: "grape", label: "Grape" }, ]; return ( ); } ``` ## Examples ### Multiple Selection Enable multi-select with the `multiple` prop. Selected items appear as removable chips. ```tsx import { ComboboxField } from "@px-ui/forms"; import { useState } from "react"; export default function Example() { const [value, setValue] = useState([]); const items = [ { id: "react", label: "React" }, { id: "vue", label: "Vue" }, { id: "angular", label: "Angular" }, { id: "svelte", label: "Svelte" }, { id: "solid", label: "Solid" }, ]; return ( ); } ``` ### Async Data Loading Use `loadOptions` to fetch data dynamically based on the search query. ```tsx import { ComboboxField } from "@px-ui/forms"; import { useState } from "react"; interface User { id: number; name: string; email: string; } const searchUsers = async (query: string): Promise => { // Fetch from your API const response = await fetch(`/api/users?q=${query}`); return response.json(); }; export default function Example() { const [value, setValue] = useState(null); return ( user.name} renderOption={(user) => (
{user.name} {user.email}
)} /> ); } ``` ### Sizes Control the size of the combobox field using the `size` prop. ```tsx import { ComboboxField } from "@px-ui/forms"; import { useState } from "react"; export default function Example() { const [value, setValue] = useState(null); const items = [ { id: "sm", label: "Small" }, { id: "md", label: "Medium" }, { id: "lg", label: "Large" }, ]; return (
); } ``` ### Search in Popup Display the search input inside the dropdown instead of the trigger by using `searchInPopup`. ```tsx import { ComboboxField } from "@px-ui/forms"; import { useState } from "react"; export default function Example() { const [value, setValue] = useState([]); const items = [ { id: "typescript", label: "TypeScript" }, { id: "javascript", label: "JavaScript" }, { id: "python", label: "Python" }, ]; return ( ); } ``` ## API Reference ### ComboboxField The main combobox field component that wraps the Combobox component from `@px-ui/core`. #### Custom Props | Prop | Type | Default | Description | | --------------------- | ---------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `items` | `ReadonlyArray` | - | Array of items to display. Required if not using `loadOptions` | | `loadOptions` | `(query: string) => Promise` | - | Function to load options asynchronously based on search query. If provided, `items` prop is not required | | `renderLabel` | `(item: TSelectedValue \| TSelectedValue[]) => React.ReactNode` | - | Function to render the label in the trigger for the selected item(s). For single select, receives a single item. For multiple select, receives an array of items. If not provided and item has a `label` property, it will be used automatically | | `renderOption` | `(item: TItem) => React.ReactNode` | - | Function to render each option in the dropdown. If not provided and item has a `label` property, it will be used automatically | | `renderChip` | `(item: TSelectedValue) => React.ReactNode \| string` | - | Function to render each chip in ChipsTrigger (multiple selection only). If not provided, renderLabel or auto-detected label will be used | | `placeholder` | `string` | - | Placeholder text when no value is selected | | `searchInPopup` | `boolean` | `false` | Show search input inside the popup instead of in the trigger | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant for the trigger | | `widthVariant` | `'enforced' \| 'full'` | `'full'` | Width variant for the trigger | | `contentWidthVariant` | `'trigger' \| 'fit' \| 'enforced'` | `'trigger'` | Width variant for the dropdown content | | `triggerClassName` | `string` | - | Additional CSS classes for the trigger element | | `contentProps` | `Omit, 'children' \| 'widthVariant' \| 'empty'>` | - | Additional props for Combobox.Content component | #### Inherited Props from Combobox.Root | Prop | Type | Default | Description | | -------------------- | ------------------------------------------------------------- | ------- | --------------------------------------------------------------------------- | | `value` \* | `TSelectedValue \| TSelectedValue[] \| null` | - | The current selected value(s) | | `onValueChange` \* | `(value: TSelectedValue \| TSelectedValue[] \| null) => void` | - | Callback fired when the selected value changes | | `multiple` | `boolean` | `false` | Whether multiple items can be selected | | `disabled` | `boolean` | `false` | Whether the combobox is disabled | | `invalid` | `boolean` | `false` | Whether the combobox is in an invalid state | | `readOnly` | `boolean` | `false` | Whether the combobox is read-only | | `isItemEqualToValue` | `(item: TItem, value: TSelectedValue) => boolean` | - | Custom equality function to compare items. By default, uses strict equality | | `inputRef` | `React.Ref` | - | Ref to the hidden input element used for form submission | *\* Required prop* ## Notes * For single selection, ComboboxField uses `SearchableTrigger` by default, allowing inline search * For multiple selection, ComboboxField uses `ChipsTrigger` by default, displaying selected items as removable chips * When `searchInPopup` is true, a regular `Trigger` is used and search appears in the dropdown * ComboboxField automatically detects `label`, `id`, or `value` properties from items for key generation and display * The component is fully type-safe and infers the item type from the `items` array or `loadOptions` return type * For complex layouts or custom sub-component composition, use the full `Combobox` component from `@px-ui/core` # Combobox (/docs/components/combobox) import { ComboboxBasicDemo } from "../../../src/components/combobox-basic-demo"; import { ComboboxSearchableDemo } from "../../../src/components/combobox-searchable-demo"; import { ComboboxMultipleDemo } from "../../../src/components/combobox-multiple-demo"; import { ComboboxWithSearchDemo } from "../../../src/components/combobox-with-search-demo"; ## Overview The Combobox component combines a text input with a dropdown list, allowing users to search and select values with autocomplete functionality. It supports single and multiple selection, async data loading, and infinite scrolling. ## Import ```tsx import { Combobox } from "@px-ui/core"; ``` ## Usage ```tsx const [value, setValue] = useState(null); const fruits = [ { value: "apple", label: "Apple" }, { value: "banana", label: "Banana" }, { value: "orange", label: "Orange" }, ]; {fruits.map((fruit) => ( {fruit.label} ))} ``` ## Examples ### Searchable Trigger Use a searchable trigger to allow users to type and filter options as they search. ```tsx const [value, setValue] = useState(null); {countries.map((country) => ( {country.label} ))} ``` ### Multiple Selection Enable multi-select mode with chips to allow users to select multiple options. ```tsx const [value, setValue] = useState([]); {(item: any) => ( {item.label} )} {languages.map((language) => ( {language.label} ))} ``` ### With Search Field Add a dedicated search field within the dropdown for better filtering of large lists. ```tsx {users.map((user) => ( {user.label} ))} ``` ## Anatomy Components that make up `Combobox`: ### `Combobox.Root` The root container that manages combobox state and coordinates all combobox components. **Custom Props:** | Prop | Type | Default | Description | | --------------- | ------------------- | ------- | ------------------------------------------- | | `value` | `Value \| Value[]` | - | Selected value(s) | | `onValueChange` | `(value) => void` | - | Callback when selection changes | | `multiple` | `boolean` | `false` | Enable multi-select mode | | `disabled` | `boolean` | `false` | Whether the combobox is disabled | | `invalid` | `boolean` | `false` | Whether the combobox is in an invalid state | | `isLoading` | `boolean` | `false` | Whether options are loading | | `loadOptions` | `LoadOptionsConfig` | - | Async options loading configuration | **Inherited Props:** Inherits all props from [Base UI Combobox.Root](https://base-ui.com/react/components/combobox#root) *** ### `Combobox.Trigger` Button that opens the combobox dropdown when clicked. **Custom Props:** | Prop | Type | Default | Description | | -------------- | ------------------------------- | ------------ | ----------------------------- | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the trigger button | | `widthVariant` | `"fit" \| "enforced" \| "full"` | `"enforced"` | Width behavior of the trigger | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Combobox.Trigger](https://base-ui.com/react/components/combobox#trigger) *** ### `Combobox.SearchableTrigger` Input-based trigger that allows typing to search and filter options. **Custom Props:** | Prop | Type | Default | Description | | -------------- | ------------------------------- | ----------- | ------------------------------- | | `placeholder` | `string` | - | Placeholder text for the input | | `size` | `"default" \| "sm"` | `"default"` | Size of the input | | `widthVariant` | `"enforced" \| "fit" \| "full"` | `"full"` | Width behavior | | `addons` | `ReactNode` | - | Additional addons for the input | | `className` | `string` | - | Additional CSS classes | *** ### `Combobox.ChipsTrigger` Multi-select trigger that displays selected values as removable chips. **Custom Props:** | Prop | Type | Default | Description | | -------------- | ---------------------- | ------------ | ----------------------------------- | | `placeholder` | `string` | - | Placeholder when no values selected | | `children` | `function` | - | Render function for each chip | | `size` | `"default" \| "sm"` | `"default"` | Size of the trigger | | `widthVariant` | `"enforced" \| "full"` | `"enforced"` | Width behavior | | `className` | `string` | - | Additional CSS classes | *** ### `Combobox.Value` Displays the currently selected value or placeholder text. **Custom Props:** | Prop | Type | Default | Description | | ------------- | ----------------------- | ------- | -------------------------------------- | | `placeholder` | `string` | - | Text to show when no value is selected | | `children` | `ReactNode \| function` | - | Custom render function for the value | | `className` | `string` | - | Additional CSS classes | *** ### `Combobox.Content` The dropdown content container with positioning and animations. **Custom Props:** | Prop | Type | Default | Description | | ----------------- | ---------------------------------- | -------------- | ---------------------------------- | | `empty` | `string` | `"No options"` | Text to show when no options match | | `widthVariant` | `"trigger" \| "fit" \| "enforced"` | `"trigger"` | Width behavior | | `portalProps` | `object` | - | Props for the portal component | | `positionerProps` | `object` | - | Props for the positioner component | | `popupProps` | `object` | - | Props for the popup component | *** ### `Combobox.List` Container for combobox items, handles scrolling and keyboard navigation. **Inherited Props:** Inherits all props from [Base UI Combobox.List](https://base-ui.com/react/components/combobox#list) *** ### `Combobox.Item` Individual selectable option in the dropdown. **Custom Props:** | Prop | Type | Default | Description | | ----------- | --------- | ------- | ------------------------------ | | `value` | `any` | - | Value of this option | | `disabled` | `boolean` | `false` | Whether the option is disabled | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Combobox.Item](https://base-ui.com/react/components/combobox#item) *** ### `Combobox.MultiItem` Item component for multi-select mode with checkbox indicator. **Custom Props:** | Prop | Type | Default | Description | | ----------- | --------- | ------- | ------------------------------ | | `value` | `any` | - | Value of this option | | `disabled` | `boolean` | `false` | Whether the option is disabled | | `className` | `string` | - | Additional CSS classes | *** ### `Combobox.Chip` Chip component for displaying selected values in multi-select mode. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Combobox.Chip](https://base-ui.com/react/components/combobox#chip) *** ### `Combobox.Search` Dedicated search input field within the dropdown for filtering options. **Custom Props:** | Prop | Type | Default | Description | | ------------- | -------- | ------------------ | ---------------- | | `placeholder` | `string` | `"Search options"` | Placeholder text | **Inherited Props:** Inherits all props from [Base UI Combobox.Input](https://base-ui.com/react/components/combobox#input) *** ## API Reference See the [Anatomy](#anatomy) section above for detailed component props. # Currency Select Field (/docs/components/currency-select-field) import CurrencySelectFieldBasicDemo from "../../../src/components/currency-select-field-basic-demo.tsx"; import CurrencySelectFieldWithFieldDemo from "../../../src/components/currency-select-field-with-field-demo.tsx"; ## Overview CurrencySelectField is a specialized select component designed for currency selection. It displays currencies with their country flags, abbreviations, and full names. The component includes built-in search functionality and automatically displays country flags based on the currency abbreviation using the built-in `CURRENCY_FLAG_CODE` mapping. ## Import ```tsx import { CurrencySelectField, type Currency } from "@px-ui/forms"; ``` ## Usage ```tsx import { CurrencySelectField, type Currency } from "@px-ui/forms"; import { useState } from "react"; const currencies: Currency[] = [ { id: "1", abbr: "USD", name: "United States dollar", value: "USD" }, { id: "2", abbr: "CAD", name: "Canadian dollar", value: "CAD" }, { id: "3", abbr: "EUR", name: "Euro", value: "EUR" }, { id: "4", abbr: "GBP", name: "British Pound", value: "GBP" }, { id: "5", abbr: "INR", name: "Indian Rupee", value: "INR" }, { id: "6", abbr: "AUD", name: "Australian Dollar", value: "AUD" }, ]; export default function Example() { const [value, setValue] = useState(null); return ( ); } ``` ## Examples ### With Field Component Use with the Field component for form layouts with labels and error states. ```tsx import { CurrencySelectField, Field, type Currency } from "@px-ui/forms"; import { useState } from "react"; export default function Example() { const [value, setValue] = useState(null); const [error, setError] = useState(null); return ( Currency * {error && {error}} ); } ``` ## API Reference ### CurrencySelectField The main currency select component. #### Props | Prop | Type | Default | Description | | --------------------- | ----------------------------------- | ------------------- | --------------------------------------------------------------- | | `currencies` \* | `ReadonlyArray` | - | Array of currency options to display | | `value` | `Currency \| null` | - | The currently selected currency | | `onValueChange` | `(value: Currency \| null) => void` | - | Callback fired when the selected currency changes | | `placeholder` | `string` | `"Select currency"` | Placeholder text when no currency is selected | | `disabled` | `boolean` | `false` | Whether the select is disabled | | `invalid` | `boolean` | `false` | Whether the select is in an invalid state | | `readOnly` | `boolean` | `false` | Whether the select is read-only | | `name` | `string` | - | Name attribute for form submission (submits the currency value) | | `size` | `'default' \| 'sm'` | `'default'` | Size variant for the trigger | | `widthVariant` | `'enforced' \| 'full'` | `'enforced'` | Width variant for the trigger | | `contentWidthVariant` | `'trigger' \| 'fit' \| 'enforced'` | `'trigger'` | Width variant for the dropdown content | | `triggerClassName` | `string` | - | Additional CSS classes for the trigger element | | `isLoading` | `boolean` | `false` | Whether the select is in a loading state | | `contentProps` | `object` | - | Additional props for Combobox.Content component | | `inputRef` | `React.Ref` | - | Ref to the input element | *\* Required prop* ### Currency Type ```tsx interface Currency { /** Unique identifier for the currency */ id: string; /** Full currency name (e.g., "United States dollar") */ name: string; /** Currency abbreviation (e.g., "USD", "EUR") */ abbr: string; /** Currency value/code used for form submission */ value: string; } ``` ## Notes * Search/filter functionality is built-in - users can type to filter currencies by abbreviation or name * The `name` prop submits the currency `value` to forms * Currencies are compared by their `id` property for selection state * Country flags are automatically displayed based on the currency `abbr` using the built-in `CURRENCY_FLAG_CODE` mapping * The component uses `react-country-flag` for SVG flag rendering * For currencies like EUR that don't map to a single country, the mapping uses special codes like "EU" ## CURRENCY\_FLAG\_CODE The component exports `CURRENCY_FLAG_CODE`, a constant that maps currency abbreviations to country codes. This is used internally to display country flags. You can import it if you need to check which currencies have flag support: ```tsx import { CURRENCY_FLAG_CODE } from "@px-ui/forms"; // Check if a currency has a flag mapping const hasFlag = currency.abbr in CURRENCY_FLAG_CODE; ``` # Date Picker (/docs/components/date-picker) import { DatePickerBasicDemo } from "../../../src/components/date-picker-basic-demo"; import { DatePickerRangeDemo } from "../../../src/components/date-picker-range-demo"; import { DatePickerFormatDemo } from "../../../src/components/date-picker-format-demo"; import { DatePickerDisabledDemo } from "../../../src/components/date-picker-disabled-demo"; ## Overview The DatePicker component combines a trigger button with a calendar popover, providing an intuitive interface for date selection. It supports various date formats, single dates, date ranges, and disabled date handling. ## Import ```tsx import { DatePicker } from "@px-ui/core"; ``` ## Usage ```tsx const [selected, setSelected] = useState(undefined); ``` ## Examples ### Range Selection Allow users to select a date range by enabling range mode. ```tsx const [selected, setSelected] = useState(undefined); ``` ### Date Formats Customize the date format displayed in the trigger using the `format` prop with date-fns format strings. ```tsx ``` ### Disabled Dates Restrict date selection by disabling past dates, future dates, or specific dates. ```tsx // Disable past dates // Disable future dates // Disable specific dates ``` ## API Reference ### DatePicker The main date picker component combining trigger and calendar. | Prop | Type | Default | Description | | ---------------------- | ----------------------------------- | ------------------ | ------------------------------------------- | | `mode` | `"single" \| "multiple" \| "range"` | `"single"` | Selection mode for dates | | `selected` | `Date \| Date[] \| DateRange` | - | Currently selected date(s) | | `onSelect` | `function` | - | Callback when date selection changes | | `placeholder` | `string` | `"Pick a date"` | Placeholder text for the trigger | | `format` | `string` | `"yyyy-MM-dd"` | Date format string (date-fns format) | | `disabled` | `Date \| Date[] \| function` | - | Dates that cannot be selected | | `invalid` | `boolean` | `false` | Whether the date picker is in invalid state | | `trailingIcon` | `ReactNode` | `` | Icon shown at the end of the trigger | | `renderTriggerContent` | `ReactNode` | - | Custom content for the trigger | | `triggerProps` | `object` | - | Props for the trigger button | | `popoverRootProps` | `object` | - | Props for the popover root | | `popoverContentProps` | `object` | - | Props for the popover content | **Calendar Props:** All Calendar component props are also supported. *** ### TriggerProps The `triggerProps` object accepts the following properties: | Prop | Type | Default | Description | | -------------- | ------------------------------- | ------------ | ------------------------------- | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the trigger button | | `widthVariant` | `"fit" \| "enforced" \| "full"` | `"enforced"` | Width behavior of the trigger | | `disabled` | `boolean` | `false` | Whether the trigger is disabled | | `className` | `string` | - | Additional CSS classes | *** ## Common Patterns ### Custom Date Format Use date-fns format strings to customize date display: ```tsx // US format // European format // Long format // Short format with weekday ``` ### With Default Value Set an initial selected date: ```tsx ``` ### Size Variants Control the size of the trigger: ```tsx ``` ### Disabled State Disable the entire date picker: ```tsx ``` # Dialog (/docs/components/dialog) import { DialogBasicDemo } from "../../../src/components/dialog-basic-demo"; import { DialogWithIconDemo } from "../../../src/components/dialog-with-icon-demo"; import { DialogConfirmationDemo } from "../../../src/components/dialog-confirmation-demo"; import { DialogFormDemo } from "../../../src/components/dialog-form-demo"; ## Overview The Dialog component displays content in a modal overlay that captures the user's attention and requires interaction before returning to the main application. It includes smooth animations, backdrop overlay, and built-in accessibility features. ## Import ```tsx import { Dialog } from "@px-ui/core"; ``` ## Usage ```tsx } /> Account Settings Make changes to your account settings here.

Update your profile information, preferences, and account details.

} /> ``` ## Examples ### With Icon Add a visual icon to the dialog header to provide context for the action or content. ```tsx } /> Share this document Anyone with the link will be able to view this document.
{/* Share content */}
} /> ``` ### Confirmation Dialog Use dialogs to confirm destructive or important actions before proceeding. ```tsx } /> Delete Account Are you sure you want to delete your account? This action cannot be undone.

All your data, projects, and settings will be permanently removed.

} /> ``` ### Form Dialog Dialogs can contain forms for collecting user input without leaving the current page context. ```tsx } /> Create New Project Enter the details for your new project.
} /> ``` ## Anatomy Components that make up `Dialog`: ### `Dialog.Root` The root container that manages dialog state and coordinates all dialog components. **Custom Props:** | Prop | Type | Default | Description | | -------------- | ------------------------- | ------- | --------------------------------- | | `open` | `boolean` | - | Controlled open state | | `defaultOpen` | `boolean` | `false` | Default open state (uncontrolled) | | `onOpenChange` | `(open: boolean) => void` | - | Callback when open state changes | **Inherited Props:** Inherits all props from [Base UI Dialog.Root](https://base-ui.com/react/components/dialog#root) *** ### `Dialog.Trigger` Button that opens the dialog when clicked. **Custom Props:** | Prop | Type | Default | Description | | -------- | ---------------------- | ------- | -------------------------------------- | | `render` | `(props) => ReactNode` | - | Render prop for custom trigger element | **Inherited Props:** Inherits all props from [Base UI Dialog.Trigger](https://base-ui.com/react/components/dialog#trigger) *** ### `Dialog.Content` The main dialog content container with overlay, animations, and close button. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Dialog.Popup](https://base-ui.com/react/components/dialog#popup) *** ### `Dialog.Header` Container for the dialog title, description, and optional icon. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `div` props *** ### `Dialog.HeaderIcon` Optional icon container displayed at the start of the header. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `div` props *** ### `Dialog.HeaderContent` Container for title and description in the header. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `div` props *** ### `Dialog.Title` The dialog title element, important for accessibility. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Dialog.Title](https://base-ui.com/react/components/dialog#title) *** ### `Dialog.Description` Optional description providing more context about the dialog. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Dialog.Description](https://base-ui.com/react/components/dialog#description) *** ### `Dialog.Footer` Container for action buttons at the bottom of the dialog. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `div` props *** ### `Dialog.Close` Button that closes the dialog when clicked. **Custom Props:** | Prop | Type | Default | Description | | -------- | ---------------------- | ------- | ------------------------------------ | | `render` | `(props) => ReactNode` | - | Render prop for custom close element | **Inherited Props:** Inherits all props from [Base UI Dialog.Close](https://base-ui.com/react/components/dialog#close) *** ### `Dialog.Portal` Portal component for rendering dialog content outside the DOM hierarchy. **Inherited Props:** Inherits all props from [Base UI Dialog.Portal](https://base-ui.com/react/components/dialog#portal) *** ### `Dialog.Overlay` The backdrop overlay behind the dialog content. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Dialog.Backdrop](https://base-ui.com/react/components/dialog#backdrop) *** ## API Reference See the [Anatomy](#anatomy) section above for detailed component props. # Field (/docs/components/field) import { FieldBasicDemo } from "../../../src/components/field-basic-demo"; import { FieldWithErrorDemo } from "../../../src/components/field-with-error-demo"; import { FieldHorizontalDemo } from "../../../src/components/field-horizontal-demo"; import { FieldGroupDemo } from "../../../src/components/field-group-demo"; ## Overview The Field component provides a complete form field structure with label, description, error messages, and flexible layout options. It helps maintain consistent spacing and styling across form inputs while handling validation states. ## Import ```tsx import { Field } from "@px-ui/forms"; ``` ## Usage ```tsx Email We'll never share your email with anyone else. ``` ## Examples ### With Error Display validation errors below the input field. ```tsx Username Username must be at least 3 characters long ``` ### Horizontal Layout Use horizontal orientation for side-by-side label and input layouts. ```tsx Full Name Enter your first and last name Email Notifications Receive email updates about your account ``` ### Field Group Group multiple related fields with consistent spacing. ```tsx First Name Last Name Email We'll never share your email with anyone else. ``` ## Anatomy Components that make up `Field`: ### `Field.Root` The root container for a form field, managing layout and state. **Custom Props:** | Prop | Type | Default | Description | | --------------- | -------------------------------------------- | ------------ | ---------------------------------------- | | `orientation` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` | Layout direction of the field | | `data-invalid` | `string` | - | Set to "true" to indicate invalid state | | `data-disabled` | `string` | - | Set to "true" to indicate disabled state | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `div` props *** ### `Field.Label` Label element for the form field, connected to the input via `htmlFor`. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------------------- | | `htmlFor` | `string` | - | ID of the associated input element | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from the Label component *** ### `Field.Title` Alternative to Label for non-input field labels (used in horizontal layouts). **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `div` props *** ### `Field.Description` Helper text providing additional context about the field. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `p` props *** ### `Field.Error` Error message display for validation feedback. **Custom Props:** | Prop | Type | Default | Description | | ----------- | ----------------------------- | ------- | --------------------------------- | | `errors` | `Array<{ message?: string }>` | - | Array of error objects to display | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `div` props *** ### `Field.Content` Container for grouping title and description (used in horizontal layouts). **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `div` props *** ### `Field.Group` Container for grouping multiple related fields with consistent spacing. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `div` props *** ### `Field.Set` Semantic fieldset wrapper for related form fields. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `fieldset` props *** ### `Field.Legend` Legend element for fieldsets. **Custom Props:** | Prop | Type | Default | Description | | ----------- | --------------------- | ---------- | ---------------------- | | `variant` | `"legend" \| "label"` | `"legend"` | Visual style variant | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `legend` props *** ### `Field.Separator` Visual separator between fields with optional centered text. **Custom Props:** | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ----------------------------------------------- | | `children` | `ReactNode` | - | Optional text to display in center of separator | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `div` props *** ## API Reference See the [Anatomy](#anatomy) section above for detailed component props. ## Common Patterns ### With Multiple Errors Display multiple validation errors: ```tsx Password ``` ### Responsive Layout Use responsive orientation for mobile-first designs: ```tsx Settings Configure your preferences ``` ### With Separator Separate sections of a form: ```tsx Name Contact Information Email ``` # File Upload (/docs/components/file-upload) import { SimpleUploadDemo, SimpleUploadWithS3Demo, SimpleButtonVariantDemo, SimpleImageGridDemo, BasicDropzoneDemo, MultipleFilesListDemo, UploadWithProgressDemo, FilesTableDemo, DropzoneSizesDemo, MixedContentCardsDemo, AvatarUploadDemo, } from "../../../src/components/file-upload-demos"; ## Overview The File Upload system gives you two ways to build file upload experiences: use `FileUploadField` for a ready-to-use component, or combine `useFileUpload` with the `FileUpload.*` primitives for fully custom UIs. ## Import ```tsx // Recommended: ready-to-use component import { FileUploadField } from "@px-ui/forms"; // Advanced: hook + composable primitives import { FileUpload, useFileUpload } from "@px-ui/core"; ``` ## Usage This example uses `FileUploadField`, which includes state management, validation, and optional upload support. ```tsx import { FileUploadField } from "@px-ui/forms"; export function Uploader() { return ( console.log(files)} /> ); } ``` ## Examples ### With S3/presigned uploads Configure uploads by providing `upload.getPresignedUrl` and `upload.uploadFile`. Progress is handled for you when `uploadFile` calls `onProgress`. ```tsx import { FileUploadField } from "@px-ui/forms"; export function UploaderWithUpload() { return ( { const res = await fetch("/api/get-upload-url", { method: "POST", body: JSON.stringify({ filename, contentType, size }), }); const data = await res.json(); return { result: { url: data.url, fullPath: data.fullPath, }, }; }, uploadFile: async (url, file, presignedData, onProgress) => { // Implement upload to `url` and call `onProgress(0..100)`. // Return the final URL (or rely on `presignedData.fullPath`). await fetch(url, { method: "PUT", body: file }); onProgress?.(100); return { result: { url: presignedData.fullPath } }; }, }} /> ); } ``` ### Variants (dropzone, button, compact) `FileUploadField` supports three layout variants. ```tsx import { FileUploadField } from "@px-ui/forms"; // Dropzone (default) // Button // Compact ``` ### Image uploads with a grid For image-first workflows, render a grid instead of a list. ```tsx import { FileUploadField } from "@px-ui/forms"; ``` ### Fully custom UI (hook + primitives) Use `useFileUpload` for state/actions and pass them into `FileUpload.Root`. Everything else is composed with `FileUpload.*`. ```tsx import { FileUpload, useFileUpload } from "@px-ui/core"; export function CustomDropzone() { const [state, actions] = useFileUpload({ onFilesChange: (files) => console.log(files), }); return ( ); } ``` ### List view for mixed file types A list layout is useful for documents and mixed uploads. ### Upload progress UI If you enable uploads (via the hook’s `upload` option), you can surface progress with `ItemProgress` and status with `ItemStatus`. ### Table and card layouts Because the primitives are headless/composable, you can render your own layouts. ### Dropzone sizes ```tsx ``` ### Avatar upload ```tsx export function AvatarUploadDemo() { const [state, actions] = useFileUpload({ accept: "image/*", maxSize: 2 * 1024 * 1024, multiple: false, }); return (
{state.files.length > 0 ? ( Avatar ) : (
Upload
)}

Click or drag to upload avatar

); } ``` ## Anatomy The file upload primitives are designed to be composed together. Most apps follow this structure: * **`FileUpload.Root`**: Provides context for all child components * **`FileUpload.Dropzone`**: Drag-and-drop area (also supports paste and keyboard) * **`FileUpload.Trigger`**: Standalone “open file dialog” button * **`FileUpload.ItemList` / `FileUpload.Item`**: Render selected files * **`FileUpload.ImageGrid` / `FileUpload.ImageGridItem`**: Render images in a grid * **`FileUpload.*` item parts**: `ItemPreview`, `ItemName`, `ItemSize`, `ItemStatus`, `ItemProgress`, `ItemError`, `ItemRetry`, `ItemRemove` * **`FileUpload.ClearButton`**: Clear all selected files ## API Reference ### FileUploadField A ready-to-use upload component that internally uses `useFileUpload` and the `FileUpload.*` primitives. | Prop | Type | Default | Description | | ---------------- | ------------------------------------------------------------------------------ | ----------------------------------- | ---------------------------------------- | | `variant` | `"dropzone" \| "button" \| "compact"` | `"dropzone"` | Layout variant | | `size` | `"sm" \| "default" \| "lg"` | `"default"` | Dropzone size (dropzone variant) | | `dropzoneText` | `string` | `"Paste Or Drag & Drop Files Here"` | Dropzone label text | | `buttonText` | `string` | `"Browse for files"` | Trigger button label | | `showFileList` | `boolean` | `true` | Show file list below the control | | `showImageGrid` | `boolean` | `false` | Show an image grid instead of a list | | `initialFiles` | `Array<{ id: string; name: string; size: number; type: string; url: string }>` | `[]` | Pre-populate with already-uploaded files | | `disabled` | `boolean` | `false` | Disable all interactions | | `renderFileItem` | `(file, actions) => React.ReactNode` | - | Custom renderer for list items | | `onError` | `(error: { type: string; message: string; files?: File[] }) => void` | - | Validation errors callback | **Also accepts hook options:** `accept`, `multiple`, `maxSize`, `maxFiles`, `onFilesChange`, `onFilesAdded`, and `upload`. *** ### useFileUpload A hook that manages file selection, validation, previews, and (optionally) uploads. **Options** (partial): | Option | Type | Default | Description | | --------------- | ---------------------- | ---------- | ------------------------------------------- | | `accept` | `string` | `"*"` | Accepted file types (e.g. `"image/*,.pdf"`) | | `multiple` | `boolean` | `false` | Allow multiple files | | `maxSize` | `number` | `Infinity` | Max file size in bytes | | `maxFiles` | `number` | `Infinity` | Max file count (only when `multiple`) | | `initialFiles` | `FileMetadata[]` | `[]` | Pre-populate with uploaded files | | `onFilesChange` | `(files) => void` | - | Called when files change | | `onFilesAdded` | `(addedFiles) => void` | - | Called with only newly-added files | | `upload` | `UploadConfig` | - | Enables uploads and progress tracking | **Returns**: `[state, actions]` * **State**: `{ files, isDragging, errors, isUploading }` * **Actions**: `addFiles`, `removeFile`, `clearFiles`, `clearErrors`, `openFileDialog`, `getInputProps`, drag handlers, plus upload actions `uploadFiles`, `retryUpload`, `cancelUpload`. *** ### FileUpload.Root Context provider and wiring point for `useFileUpload`. | Prop | Type | Required | Description | | ----------------- | ------------------------------------- | -------- | -------------------------------------------------------- | | `files` | `FileUploadFile[]` | Yes | Files from `useFileUpload().files` | | `addFiles` | `(files: FileList \| File[]) => void` | Yes | Adds files | | `removeFile` | `(id: string) => void` | Yes | Removes a file | | `clearFiles` | `() => void` | Yes | Clears all files | | `retryUpload` | `(id: string) => Promise` | No | Enables retry UI (`ItemRetry`, image-grid retry overlay) | | `openFileDialog` | `() => void` | Yes | Opens native file picker | | `getInputProps` | `(props?) => InputProps` | Yes | Props for the internal `` | | `handleDragEnter` | `(e) => void` | Yes | Drag enter handler | | `handleDragLeave` | `(e) => void` | Yes | Drag leave handler | | `handleDragOver` | `(e) => void` | Yes | Drag over handler | | `handleDrop` | `(e) => void` | Yes | Drop handler | | `isDragActive` | `boolean` | No | Hook’s `isDragging` state | | `isUploading` | `boolean` | No | Hook’s `isUploading` state | | `accept` | `string` | No | Accepted types (used by Dropzone/input) | | `multiple` | `boolean` | No | Allow multiple file selection | | `disabled` | `boolean` | No | Disable all interactions | | `className` | `string` | No | Additional CSS classes | *** ### FileUpload.Dropzone Drag-and-drop area (also supports paste, and keyboard Enter/Space). | Prop | Type | Default | Description | | -------------------- | --------------------------- | ----------------------------------- | -------------------------------------------------- | | `size` | `"sm" \| "default" \| "lg"` | `"default"` | Dropzone size | | `dropzoneText` | `string` | `"Paste Or Drag & Drop Files Here"` | Primary label | | `browseText` | `string` | `"Browse for files"` | Button label | | `hideDefaultContent` | `boolean` | `false` | Hide built-in UI so you can render custom children | **Inherited Props:** All native `div` props. *** ### FileUpload.Trigger Standalone trigger button for opening the file dialog. | Prop | Type | Default | Description | | -------------------- | --------- | ---------------- | -------------------------------------------------- | | `uploadingText` | `string` | `"Uploading..."` | Text shown when `showUploadingState` and uploading | | `showUploadingState` | `boolean` | `true` | Disable + show spinner/text during uploads | **Inherited Props:** All `Button` props. *** ### FileUpload.ItemList Renders nothing when there are no files. | Prop | Type | Default | Description | | ---------- | ------------------------------------- | ------- | -------------------------------------- | | `children` | `ReactNode \| ((files) => ReactNode)` | - | Render prop receives the current files | **Inherited Props:** All native `div` props. *** ### FileUpload.Item Wraps a file row and provides item context for `Item*` parts. | Prop | Type | Default | Description | | -------------- | ---------------- | ------- | -------------------------------------------- | | `file` | `FileUploadFile` | - | The file object (required) | | `statusStyles` | `boolean` | `true` | Apply error styling when status is `"error"` | **Inherited Props:** All native `div` props. *** ### FileUpload.ItemPreview | Prop | Type | Default | Description | | ---------- | ----------------- | -------------- | ------------------------------------- | | `fallback` | `React.ReactNode` | `` | Fallback when no preview is available | **Inherited Props:** All native `div` props. *** ### FileUpload.ItemStatus | Prop | Type | Default | Description | | ------------------ | ----------------- | --------------- | ------------------------ | | `successIcon` | `React.ReactNode` | `` | Custom success icon | | `uploadingContent` | `React.ReactNode` | `"{progress}%"` | Custom uploading content | | `errorContent` | `React.ReactNode` | `"Failed"` | Custom error content | **Inherited Props:** All native `div` props. *** ### FileUpload.ImageGrid | Prop | Type | Default | Description | | ---------- | ------------------------------------- | ------- | -------------------------------------- | | `children` | `ReactNode \| ((files) => ReactNode)` | - | Render prop receives the current files | **Inherited Props:** All native `div` props. *** ### FileUpload.ImageGridItem | Prop | Type | Default | Description | | ------------------- | ---------------- | ------- | ------------------------------------- | | `file` | `FileUploadFile` | - | The file object (required) | | `showStatusOverlay` | `boolean` | `true` | Show uploading/error/success overlays | **Inherited Props:** All native `div` props. ``` ``` # Form Components (/docs/components/form-components) import FormInputBasicDemo from "../../../src/components/form-input-basic-demo.tsx"; import FormInputValidationDemo from "../../../src/components/form-input-validation-demo.tsx"; import FormTextareaBasicDemo from "../../../src/components/form-textarea-basic-demo.tsx"; import FormCheckboxBasicDemo from "../../../src/components/form-checkbox-basic-demo.tsx"; import FormMixedDemo from "../../../src/components/form-mixed-demo.tsx"; ## Overview Form components are pre-built wrappers that combine Field components with Input, Textarea, and Checkbox controls, integrated with react-hook-form's Controller. They provide a quick way to build forms with consistent styling, validation, and error handling out of the box. These components are ideal for simple to medium complexity forms. For more complex scenarios (like radio groups or custom controls), use the Field components directly with react-hook-form's Controller. ## Import ```tsx import { FormInput, FormTextarea, FormCheckbox } from "@px-ui/forms"; ``` ## Usage ### FormInput Basic text input with label and description. ```tsx import { FormInput } from "@px-ui/forms"; import { useForm } from "react-hook-form"; import { Button } from "@px-ui/core"; interface FormData { email: string; username: string; } export default function Example() { const { control, handleSubmit } = useForm({ defaultValues: { email: "", username: "", }, }); const onSubmit = (data: FormData) => { console.log("Form submitted:", data); }; return (
); } ``` ## Examples ### With Validation Form inputs automatically show validation errors from react-hook-form. Mark fields as required with the `required` prop to add a visual indicator. ```tsx import { FormInput } from "@px-ui/forms"; import { useForm } from "react-hook-form"; import { Button } from "@px-ui/core"; interface FormData { email: string; age: string; } export default function Example() { const { control, handleSubmit } = useForm({ defaultValues: { email: "", age: "", }, }); const onSubmit = (data: FormData) => { console.log("Form submitted:", data); }; return (
); } ``` ### FormTextarea Multi-line text input for longer content. ```tsx import { FormTextarea } from "@px-ui/forms"; import { useForm } from "react-hook-form"; import { Button } from "@px-ui/core"; interface FormData { message: string; feedback: string; } export default function Example() { const { control, handleSubmit } = useForm({ defaultValues: { message: "", feedback: "", }, }); const onSubmit = (data: FormData) => { console.log("Form submitted:", data); }; return (
); } ``` ### FormCheckbox Checkbox input with horizontal layout by default. ```tsx import { FormCheckbox } from "@px-ui/forms"; import { useForm } from "react-hook-form"; import { Button } from "@px-ui/core"; interface FormData { acceptTerms: boolean; newsletter: boolean; notifications: boolean; } export default function Example() { const { control, handleSubmit } = useForm({ defaultValues: { acceptTerms: false, newsletter: false, notifications: false, }, }); const onSubmit = (data: FormData) => { console.log("Form submitted:", data); }; return (
); } ``` ### Complete Form Combining multiple form components in a single form. ```tsx import { FormInput, FormTextarea, FormCheckbox } from "@px-ui/forms"; import { useForm } from "react-hook-form"; import { Button } from "@px-ui/core"; interface FormData { name: string; email: string; message: string; subscribe: boolean; } export default function Example() { const { control, handleSubmit, reset } = useForm({ defaultValues: { name: "", email: "", message: "", subscribe: false, }, }); const onSubmit = (data: FormData) => { console.log("Form submitted:", data); reset(); }; return (
); } ``` ## API Reference ### FormInput A form input field that integrates Input with Field and react-hook-form's Controller. | Prop | Type | Default | Description | | ------------- | ----------------- | ------- | ------------------------------------------------------------------- | | `control` \* | `Control` | - | The control object from `useForm()` hook | | `name` \* | `string` | - | The name of the form field. Must match a key in your form data type | | `label` \* | `React.ReactNode` | - | Label text for the input field | | `description` | `React.ReactNode` | - | Optional description text shown below the input | | `placeholder` | `string` | - | Placeholder text displayed when the input is empty | | `required` | `boolean` | `false` | Whether the field is required. Adds a visual indicator to the label | ### FormTextarea A form textarea field that integrates Textarea with Field and react-hook-form's Controller. | Prop | Type | Default | Description | | ------------- | ----------------- | ------- | ------------------------------------------------------------------- | | `control` \* | `Control` | - | The control object from `useForm()` hook | | `name` \* | `string` | - | The name of the form field. Must match a key in your form data type | | `label` \* | `React.ReactNode` | - | Label text for the textarea field | | `description` | `React.ReactNode` | - | Optional description text shown below the textarea | | `placeholder` | `string` | - | Placeholder text displayed when the textarea is empty | | `required` | `boolean` | `false` | Whether the field is required. Adds a visual indicator to the label | ### FormCheckbox A form checkbox field that integrates Checkbox with Field and react-hook-form's Controller. Uses horizontal layout by default with the checkbox appearing before the label. | Prop | Type | Default | Description | | ------------- | ----------------- | ------- | ------------------------------------------------------------------- | | `control` \* | `Control` | - | The control object from `useForm()` hook | | `name` \* | `string` | - | The name of the form field. Must match a key in your form data type | | `label` \* | `React.ReactNode` | - | Label text for the checkbox field | | `description` | `React.ReactNode` | - | Optional description text shown below the checkbox | | `required` | `boolean` | `false` | Whether the field is required. Adds a visual indicator to the label | *\* Required prop* ## Notes * All form components automatically display validation errors from react-hook-form's validation rules * The `required` prop only adds a visual indicator (asterisk) to the label; add actual validation rules using react-hook-form's validation options * FormCheckbox uses horizontal layout with `controlFirst` by default, placing the checkbox before the label * For radio groups or more complex form controls, use the Field components directly with react-hook-form's Controller component * These components work seamlessly with react-hook-form's validation, error handling, and form state management # Input Group (/docs/components/input-group) import { InputGroupBasicDemo } from "../../../src/components/input-group-basic-demo"; import { InputGroupWithButtonDemo } from "../../../src/components/input-group-with-button-demo"; import { InputGroupTextDemo } from "../../../src/components/input-group-text-demo"; import { InputGroupSizesDemo } from "../../../src/components/input-group-sizes-demo"; ## Overview The InputGroup component combines input fields with addons like icons, text, and buttons. It provides a cohesive visual design for complex input controls while maintaining focus states and accessibility across all elements. ## Import ```tsx import { InputGroup } from "@px-ui/core"; ``` ## Usage ```tsx ``` ## Examples ### With Button Add action buttons directly within the input group for quick access to related functionality. ```tsx Subscribe ``` ### With Text Use text addons to provide context like prefixes, suffixes, or units. ```tsx https:// USD ``` ### Sizes Input groups support multiple sizes to match different design contexts. ```tsx ``` ## Anatomy Components that make up `InputGroup`: ### `InputGroup.Root` The root container that holds all input group components and manages their layout. **Custom Props:** | Prop | Type | Default | Description | | -------------- | ------------------------------- | ----------- | ----------------------------------- | | `size` | `"default" \| "sm"` | `"default"` | Size of the input group | | `widthVariant` | `"enforced" \| "fit" \| "full"` | `"full"` | Width behavior of the input group | | `disabled` | `boolean` | `false` | Whether the input group is disabled | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `div` props *** ### `InputGroup.Input` The input field within the group. **Custom Props:** | Prop | Type | Default | Description | | ----------- | --------- | ------- | ---------------------------------------- | | `invalid` | `boolean` | `false` | Whether the input is in an invalid state | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `input` props *** ### `InputGroup.Addon` Container for icons, text, or buttons displayed alongside the input. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------------------------------- | ---------------- | ---------------------- | | `align` | `"inline-start" \| "inline-end"` | `"inline-start"` | Position of the addon | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `div` props *** ### `InputGroup.Button` Button component styled to work within an input group. **Custom Props:** | Prop | Type | Default | Description | | ----------- | ---------------------------------------- | --------- | -------------------------- | | `size` | `"xs" \| "sm" \| "icon-xs" \| "icon-sm"` | `"xs"` | Size of the button | | `variant` | Button variants | `"ghost"` | Visual style of the button | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** All Button component props except size *** ### `InputGroup.Text` Text element for displaying static content like prefixes, suffixes, or units. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `span` props *** ## API Reference See the [Anatomy](#anatomy) section above for detailed component props. # Input OTP (/docs/components/input-otp) import { OtpInputDemo } from "../../../src/components/input-otp-demo"; import { OtpInputSizesDemo } from "../../../src/components/input-otp-sizes-demo"; ## Overview The Input OTP component provides a styled one-time password input field with two usage patterns: * **Prop-config-driven**: Simple API for common use cases * **Composable**: Full control over layout and structure It includes automatic styling for focus, disabled, and error states, with proper accessibility attributes and a visual caret indicator. Built on top of [input-otp](https://github.com/guilhermerodz/input-otp) by @guilhermerodz. ## Import ### Prop-config-driven API ```tsx import { OtpInput } from "@px-ui/core"; ``` ### Composable API ```tsx import { OTPInput, OtpInputGroup, OtpInputSlot, OtpInputSeparator, OTPInputContext, } from "@px-ui/core"; ``` ## Usage ## Prop-Config-Driven API The simplest way to use the OTP input is with the prop-config-driven `OtpInput` component. It handles the layout automatically based on props. ### Basic Usage ```tsx import { OtpInput } from "@px-ui/core"; ``` ### With Separator Add separators at specific positions using the `separatorAfter` prop (0-indexed positions). ```tsx // Adds separator after the 3rd digit (index 2) ``` ### Sizes The OtpInput component supports two size variants for different interface densities. ```tsx ``` ### Different Lengths Configure the OTP input for different use cases. ```tsx // 4-digit PIN // 6-digit OTP // 8-digit code ``` ### Controlled Value Use controlled value and onChange handlers. ```tsx const [value, setValue] = React.useState(""); setValue(value)} /> ``` ### Validation States The `OtpInput` component supports validation states through the `invalid` prop, which applies error styling and sets the appropriate ARIA attributes. ```tsx // Valid state (default) // Invalid state // Disabled state // Invalid and disabled ``` ## Composable API For advanced use cases where you need full control over the layout, use the composable API with `OTPInput` from `input-otp`. You'll need to create your own styled `Group`, `Slot`, and `Separator` components using the `OTPInputContext`. ### Creating Styled Components First, create your own styled components using `OTPInputContext`: ```tsx import { OTPInput, OTPInputContext } from "@px-ui/core"; import * as React from "react"; function OtpInputGroup({ className, ...props }: React.ComponentProps<"div">) { return
; } function OtpInputSlot({ index, className, ...props }: React.ComponentProps<"div"> & { index: number }) { const inputOTPContext = React.useContext(OTPInputContext); const { char, hasFakeCaret, isActive } = inputOTPContext?.slots[index] ?? {}; return (
{char} {hasFakeCaret && (
)}
); } function OtpInputSeparator({ className, ...props }: React.ComponentProps<"div">) { return (
); } ``` ### Basic Composable Usage ```tsx import { OTPInput } from "@px-ui/core"; ``` ### With Separator You can use the `` component to add a separator between the input groups. ```tsx import { OTPInput } from "@px-ui/core"; // Note: You need to create your own OtpInputGroup, OtpInputSlot, and OtpInputSeparator components ``` ### Custom Layouts Create any custom layout you need. ```tsx // 8-digit code with custom grouping (3-3-2) ``` ### Pattern Use the `pattern` prop to define a custom pattern for the OTP input. ```tsx import { REGEXP_ONLY_DIGITS_AND_CHARS } from "input-otp"; import { OTPInput } from "@px-ui/core"; // Note: OtpInputGroup and OtpInputSlot are custom components you create ``` ### Controlled You can use the `value` and `onChange` props to control the input value. ```tsx import { OTPInput } from "@px-ui/core"; // Note: OtpInputGroup and OtpInputSlot are custom components you create const [value, setValue] = React.useState(""); setValue(value)} > ``` ### Advanced: Using Context Access the OTP input context for custom slot implementations. ```tsx import { OTPInputContext } from "@px-ui/core"; function CustomSlot({ index }: { index: number }) { const context = React.useContext(OTPInputContext); const slot = context?.slots[index]; return (
{slot?.char || ""} {slot?.isActive && Active}
); } ``` ## API Reference ### OtpInput (Prop-Config-Driven) A simple, prop-config-driven component for common OTP input use cases. | Prop | Type | Default | Description | | -------------------- | ------------------------- | ----------- | ------------------------------------------------------------------ | | `length` | `number` | `6` | Number of OTP digits | | `size` | `"default" \| "sm"` | `"default"` | Size variant of the OTP input | | `separatorAfter` | `number[]` | `[]` | Positions after which to insert separators (0-indexed) | | `value` | `string` | - | Controlled value | | `onChange` | `(value: string) => void` | - | Callback fired when value changes | | `disabled` | `boolean` | `false` | When true, disables the input | | `invalid` | `boolean` | `false` | When true, applies error styling and sets `aria-invalid` attribute | | `maxLength` | `number` | - | Maximum length (overrides `length` if provided) | | `className` | `string` | - | Additional CSS classes for the input | | `containerClassName` | `string` | - | Additional CSS classes for the container | | `slotClassName` | `string` | - | Additional CSS classes for slots | | `separatorClassName` | `string` | - | Additional CSS classes for separator | **Inherited Props:** Inherits all props from the underlying `input-otp` library's `OTPInput` component (except `children` and `render`). ### OTPInput (Composable) The base component from `input-otp` library. Use this for composable layouts. You'll need to create your own styled `Group`, `Slot`, and `Separator` components using `OTPInputContext`. | Prop | Type | Default | Description | | -------------------- | ------------------------- | ------- | ------------------------------------------ | | `maxLength` | `number` | - | **Required.** Maximum number of characters | | `value` | `string` | - | Controlled value | | `onChange` | `(value: string) => void` | - | Callback fired when value changes | | `disabled` | `boolean` | `false` | When true, disables the input | | `pattern` | `RegExp` | - | Pattern to validate input against | | `className` | `string` | - | Additional CSS classes | | `containerClassName` | `string` | - | Additional CSS classes for the container | **Inherited Props:** See [input-otp documentation](https://github.com/guilhermerodz/input-otp) for full API. **Note:** `input-otp` doesn't provide styled `Group`, `Slot`, or `Separator` components. You need to create your own styled components using `OTPInputContext` to access slot state. See the "Creating Styled Components" section above for examples. ### OTPInputContext React context from `input-otp` library. Use this to access slot state for custom implementations. **Context Value:** ```tsx { slots: Array<{ char: string isActive: boolean hasFakeCaret: boolean }> // ... other internal state } ``` ## When to Use Which API ### Use Prop-Config-Driven (`OtpInput`) when: * You need a simple, standard OTP input * You want less boilerplate code * Standard layouts (4, 6, or 8 digits) are sufficient * You need quick implementation ### Use Composable API (`OTPInput` from `input-otp`) when: * You need custom layouts that don't fit standard patterns * You want full control over slot rendering * You need to integrate with custom UI components * You're building a complex authentication flow * You need pattern validation or other advanced features * You want to create your own styled components ## Notes * The prop-driven `OtpInput` component uses the `input-otp` library under the hood for core functionality * For composable usage, you need to create your own styled components using `OTPInputContext` * Each slot component must have a unique `index` prop matching its position (0, 1, 2, etc.) * The number of slots should match the `maxLength` prop value * The component automatically handles focus management and character input * Error states are controlled via the `invalid` prop (sets `aria-invalid` attribute automatically) * The `separatorAfter` prop in the config-driven API uses 0-indexed positions (e.g., `[2]` adds a separator after the 3rd digit) * For pattern validation, import regex patterns from `input-otp` (e.g., `REGEXP_ONLY_DIGITS_AND_CHARS`) * All `input-otp` exports are available from `@px-ui/core` for composable usage # Input (/docs/components/input) import { InputBasicDemo } from "../../../src/components/input-basic-demo"; import { InputSizesDemo } from "../../../src/components/input-sizes-demo"; import { InputWidthVariantsDemo } from "../../../src/components/input-width-variants-demo"; import { InputInvalidDemo } from "../../../src/components/input-invalid-demo"; ## Overview The Input component provides a styled text input field with support for different sizes, width behaviors, and validation states. It includes automatic styling for focus, disabled, and error states, with proper accessibility attributes. ## Import ```tsx import { Input } from "@px-ui/core"; ``` ## Usage ```tsx ``` ## Examples ### Sizes The Input component supports two size variants for different interface densities. ```tsx ``` ### Width Variants Control how the input handles width with two variants: enforced for a fixed minimum width, and full for 100% width. ```tsx ``` ### Invalid State The Input component supports validation states through the `invalid` prop, which applies error styling and sets the appropriate ARIA attributes. ```tsx ``` ## API Reference ### Input A styled text input component with size, width, and validation customization. | Prop | Type | Default | Description | | -------------- | ---------------------- | ----------- | ---------------------------------------------------------------------------- | | `size` | `"default" \| "sm"` | `"default"` | Size variant of the input | | `widthVariant` | `"enforced" \| "full"` | `"full"` | Width behavior - enforced uses a fixed minimum width, full stretches to 100% | | `invalid` | `boolean` | `false` | When true, applies error styling and sets `aria-invalid` attribute | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from native HTML `input` element including `type`, `value`, `onChange`, `placeholder`, `disabled`, etc. Note that the native `size` attribute is omitted in favor of the custom `size` prop. # Label (/docs/components/label) import { LabelBasicDemo } from "../../../src/components/label-basic-demo"; import { LabelWithFieldDemo } from "../../../src/components/label-with-field-demo"; ## Overview The Label component provides accessible, styled text labels for form controls. It automatically handles disabled states through peer and group relationships, ensuring consistent styling when associated form controls are disabled. ## Import ```tsx import { Label } from "@px-ui/core"; ``` ## Usage ```tsx ``` ## Examples ### With Form Fields Labels are designed to work seamlessly with all form components. Use the `htmlFor` prop to associate the label with an input. ```tsx
``` ## API Reference ### Label A styled label component with automatic disabled state handling. | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------------------------------------- | | `htmlFor` | `string` | - | ID of the form control this label is associated with | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from native HTML `label` element. **Note:** The Label component automatically reduces opacity when: * Its parent element has `data-disabled="true"` * Its peer (sibling) element has the `disabled` attribute # Menu (/docs/components/menu) import { MenuBasicDemo } from "../../../src/components/menu-basic-demo"; import { MenuWithGroupsDemo } from "../../../src/components/menu-with-groups-demo"; import { MenuRadioDemo } from "../../../src/components/menu-radio-demo"; import { MenuSizesDemo } from "../../../src/components/menu-sizes-demo"; ## Overview The Menu component displays a list of actions or options in a dropdown panel. It provides keyboard navigation, supports grouping with labels, radio selection, and includes smooth animations and flexible positioning. ## Import ```tsx import { Menu } from "@px-ui/core"; ``` ## Usage ```tsx Actions Edit Duplicate Archive Delete ``` ## Examples ### With Groups Organize menu items into logical groups with labels for better organization. ```tsx Options Editing Cut Copy Paste View Zoom In Zoom Out ``` ### Radio Selection Use radio groups for single-selection options within a menu. ```tsx const [theme, setTheme] = useState("light"); Theme: {theme} Light Dark System ``` ### Sizes Menu triggers support different sizes to match your design needs. ```tsx Small Menu Edit Delete Medium Menu Edit Delete ``` ## Anatomy Components that make up `Menu`: ### `Menu.Root` The root container that manages menu state and coordinates all menu components. **Custom Props:** | Prop | Type | Default | Description | | -------------- | ------------------------- | ------- | --------------------------------- | | `open` | `boolean` | - | Controlled open state | | `defaultOpen` | `boolean` | `false` | Default open state (uncontrolled) | | `onOpenChange` | `(open: boolean) => void` | - | Callback when open state changes | **Inherited Props:** Inherits all props from [Base UI Menu.Root](https://base-ui.com/react/components/menu#root) *** ### `Menu.Trigger` Button that opens the menu when clicked. **Custom Props:** | Prop | Type | Default | Description | | -------------- | ---------------------------------- | ------- | ----------------------------- | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the trigger button | | `widthVariant` | `"fit" \| "trigger" \| "enforced"` | `"fit"` | Width variant for the trigger | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Menu.Trigger](https://base-ui.com/react/components/menu#trigger) *** ### `Menu.Content` The menu content container with positioning and animations. **Custom Props:** | Prop | Type | Default | Description | | ----------------- | ---------------------------------- | ------- | ---------------------------------- | | `widthVariant` | `"fit" \| "trigger" \| "enforced"` | `"fit"` | Width behavior of the menu | | `portalProps` | `object` | - | Props for the portal component | | `positionerProps` | `object` | - | Props for the positioner component | | `popupProps` | `object` | - | Props for the popup component | **Inherited Props:** Props are distributed to the Base UI Portal, Positioner, and Popup components *** ### `Menu.Item` Individual menu item that can be clicked or selected. **Custom Props:** | Prop | Type | Default | Description | | ----------- | --------- | ------- | ---------------------------- | | `disabled` | `boolean` | `false` | Whether the item is disabled | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Menu.Item](https://base-ui.com/react/components/menu#item) *** ### `Menu.Separator` Visual separator line between menu items or groups. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Menu.Separator](https://base-ui.com/react/components/menu#separator) *** ### `Menu.Group` Container for grouping related menu items. **Inherited Props:** Inherits all props from [Base UI Menu.Group](https://base-ui.com/react/components/menu#group) *** ### `Menu.GroupLabel` Label for a group of menu items. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Menu.GroupLabel](https://base-ui.com/react/components/menu#grouplabel) *** ### `Menu.RadioGroup` Container for radio items allowing single selection. **Custom Props:** | Prop | Type | Default | Description | | --------------- | ------------------------- | ------- | ----------------------------------- | | `value` | `string` | - | Currently selected radio item value | | `onValueChange` | `(value: string) => void` | - | Callback when selection changes | **Inherited Props:** Inherits all props from [Base UI Menu.RadioGroup](https://base-ui.com/react/components/menu#radiogroup) *** ### `Menu.RadioItem` Radio menu item for single-selection within a group. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ------------------------ | | `value` | `string` | - | Value of this radio item | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Menu.RadioItem](https://base-ui.com/react/components/menu#radioitem) *** ## API Reference See the [Anatomy](#anatomy) section above for detailed component props. # Popover (/docs/components/popover) import { PopoverBasicDemo } from "../../../src/components/popover-basic-demo"; import { PopoverPositionsDemo } from "../../../src/components/popover-positions-demo"; import { PopoverWithFormDemo } from "../../../src/components/popover-with-form-demo"; import { PopoverWithCloseDemo } from "../../../src/components/popover-with-close-demo"; ## Overview The Popover component displays rich content in a floating panel that appears when triggered. Unlike tooltips, popovers can contain interactive elements like buttons, forms, and links. They feature smooth animations, flexible positioning, and arrow indicators. ## Import ```tsx import { Popover } from "@px-ui/core"; ``` ## Usage ```tsx } /> Quick Actions Choose an action to perform
``` ## Examples ### Positions Popovers can be positioned on any side of the trigger element using `positionerProps`. ```tsx } />

Popover positioned on top

 } />

Popover positioned on bottom

 ``` ### With Form Popovers can contain interactive forms for collecting user input. ```tsx } /> Edit Profile Update your profile information
} /> ``` ### With Close Button Add a close button for users who prefer explicit dismiss controls. ```tsx } />
Information This is some helpful information about your account.
``` ## Anatomy Components that make up `Popover`: ### `Popover.Root` The root container that manages popover state and coordinates all popover components. **Custom Props:** | Prop | Type | Default | Description | | -------------- | ------------------------- | ------- | --------------------------------- | | `open` | `boolean` | - | Controlled open state | | `defaultOpen` | `boolean` | `false` | Default open state (uncontrolled) | | `onOpenChange` | `(open: boolean) => void` | - | Callback when open state changes | **Inherited Props:** Inherits all props from [Base UI Popover.Root](https://base-ui.com/react/components/popover#root) *** ### `Popover.Trigger` The element that triggers the popover when clicked. **Custom Props:** | Prop | Type | Default | Description | | -------- | ---------------------- | ------- | -------------------------------------- | | `render` | `(props) => ReactNode` | - | Render prop for custom trigger element | **Inherited Props:** Inherits all props from [Base UI Popover.Trigger](https://base-ui.com/react/components/popover#trigger) *** ### `Popover.Content` The main popover content container with positioning, arrow, and animations. **Custom Props:** | Prop | Type | Default | Description | | ----------------- | --------- | ------- | ----------------------------------- | | `arrow` | `boolean` | `true` | Whether to show the arrow indicator | | `positionerProps` | `object` | - | Props for the positioner component | | `popupProps` | `object` | - | Props for the popup component | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** The `popupProps` accepts all props from [Base UI Popover.Popup](https://base-ui.com/react/components/popover#popup) *** ### `Popover.Header` Container for the popover title and description. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `div` props *** ### `Popover.Title` The popover title element, important for accessibility. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Popover.Title](https://base-ui.com/react/components/popover#title) *** ### `Popover.Description` Optional description providing context about the popover content. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Popover.Description](https://base-ui.com/react/components/popover#description) *** ### `Popover.Footer` Container for action buttons at the bottom of the popover. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `div` props *** ### `Popover.Close` Button that closes the popover when clicked. **Custom Props:** | Prop | Type | Default | Description | | -------- | ---------------------- | ------- | ------------------------------------ | | `render` | `(props) => ReactNode` | - | Render prop for custom close element | **Inherited Props:** Inherits all props from [Base UI Popover.Close](https://base-ui.com/react/components/popover#close) *** ### `Popover.CloseIconButton` Pre-styled close button with icon, typically placed in the header. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Standard HTML `button` props *** ## API Reference See the [Anatomy](#anatomy) section above for detailed component props. # Progress (/docs/components/progress) import { ProgressBasicDemo } from "../../../src/components/progress-basic-demo"; import { ProgressWithLabelDemo } from "../../../src/components/progress-with-label-demo"; import { ProgressSizesDemo } from "../../../src/components/progress-sizes-demo"; import { ProgressStatesDemo } from "../../../src/components/progress-states-demo"; ## Overview The Progress component provides a visual indicator for showing task completion progress. It supports customizable sizes, labels, numeric value display, and smooth animations for progress updates. ## Import ```tsx import { Progress } from "@px-ui/core"; ``` ## Usage ```tsx ``` ## Examples ### With Label and Value Combine labels and values to provide clear context about the progress. ```tsx
Uploading files...
``` ### Sizes The Progress.Track component supports three size variants for different contexts. ```tsx ``` ### Different States Show progress at different completion stages. ```tsx {/* Starting */}
Starting...
{/* In progress */}
In progress
{/* Complete */}
Complete!
``` ## Anatomy Components that make up Progress: ### Progress.Root The root container component that manages progress state. **Inherited Props:** Inherits all props from [Base UI Progress.Root](https://base-ui.com/react/components/progress#root) including `value`, `min`, `max`, etc. *** ### Progress.Track The background track that contains the progress indicator. **Custom Props:** | Prop | Type | Default | Description | | ----------- | --------------------------- | ----------- | ---------------------------- | | `size` | `"default" \| "sm" \| "lg"` | `"default"` | Height of the progress track | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Progress.Track](https://base-ui.com/react/components/progress#track). *** ### Progress.Indicator The animated fill that shows the current progress. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Progress.Indicator](https://base-ui.com/react/components/progress#indicator). *** ### Progress.Label Text label describing the progress task. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Progress.Label](https://base-ui.com/react/components/progress#label). *** ### Progress.Value Displays the numeric progress value (percentage). **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Progress.Value](https://base-ui.com/react/components/progress). ## API Reference See the Anatomy section above for detailed prop information for each component. # RadioGroup (/docs/components/radio-group) import { RadioGroupBasicDemo } from "../../../src/components/radio-group-basic-demo"; import { RadioGroupSizesDemo } from "../../../src/components/radio-group-sizes-demo"; import { RadioGroupWithDescriptionsDemo } from "../../../src/components/radio-group-with-descriptions-demo"; import { RadioGroupHorizontalDemo } from "../../../src/components/radio-group-horizontal-demo"; ## Overview The RadioGroup component provides a set of mutually exclusive options where users can select exactly one choice. It supports multiple sizes, keyboard navigation, and flexible layouts with full accessibility support. ## Import ```tsx import { RadioGroup } from "@px-ui/core"; ``` ## Usage ```tsx
``` ## Examples ### Sizes The RadioGroup.Item component supports three size variants. ```tsx ``` ### With Descriptions Radio items can be paired with labels and descriptions for better context. ```tsx

Pay with your credit or debit card

{/* More options... */} ``` ### Horizontal Layout Override the default vertical layout by applying flex-row to the Group component. ```tsx
{/* More options... */} ``` ## Anatomy Components that make up the RadioGroup: ### RadioGroup.Group The container component that manages the radio group state. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | --------------------------------------------------------------- | | `className` | `string` | - | Additional CSS classes. Default layout is `flex flex-col gap-3` | **Inherited Props:** Inherits all props from [Base UI RadioGroup](https://base-ui.com/react/components/radio-group) including `value`, `defaultValue`, `onValueChange`, `disabled`, etc. *** ### RadioGroup.Item Individual radio button within the group. **Custom Props:** | Prop | Type | Default | Description | | ----------- | --------------------------- | ----------- | ------------------------ | | `variant` | `"default"` | `"default"` | Visual style variant | | `size` | `"default" \| "sm" \| "lg"` | `"default"` | Size of the radio button | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Radio.Root](https://base-ui.com/react/components/radio#root) including `value`, `disabled`, etc. ## API Reference See the Anatomy section above for detailed prop information for each component. # SegmentedControl (/docs/components/segmented-control) import { SegmentedControlBasicDemo } from "../../../src/components/segmented-control-basic-demo"; import { SegmentedControlSizesDemo } from "../../../src/components/segmented-control-sizes-demo"; import { SegmentedControlWithIconsDemo } from "../../../src/components/segmented-control-with-icons-demo"; ## Overview The SegmentedControl component provides a pill-shaped control for mutually exclusive options, commonly used for view switching or filter selection. It features smooth transitions, clear visual feedback, and keyboard navigation support. ## Import ```tsx import { SegmentedControl } from "@px-ui/core"; ``` ## Usage ```tsx Day Week Month Year ``` ## Examples ### Sizes The SegmentedControl.Item component supports three size variants. ```tsx {/* Small */} List Grid {/* Default */} List Grid {/* Large */} List Grid ``` ### With Icons Combine icons with text labels for better visual recognition. ```tsx List Grid Cards ``` ## Anatomy Components that make up SegmentedControl: ### SegmentedControl.Root The container component that manages the segmented control state. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI RadioGroup](https://base-ui.com/react/components/radio-group) including `value`, `defaultValue`, `onValueChange`, `disabled`, etc. *** ### SegmentedControl.Item Individual segment within the control. **Custom Props:** | Prop | Type | Default | Description | | ----------- | --------------------------- | ----------- | ---------------------- | | `variant` | `"default"` | `"default"` | Visual style variant | | `size` | `"default" \| "sm" \| "lg"` | `"default"` | Size of the segment | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Radio.Root](https://base-ui.com/react/components/radio#root) including `value`, `disabled`, etc. ## API Reference See the Anatomy section above for detailed prop information for each component. # Select Field (/docs/components/select-field) import SelectFieldBasicDemo from "../../../src/components/select-field-basic-demo.tsx"; import SelectFieldMultipleDemo from "../../../src/components/select-field-multiple-demo.tsx"; import SelectFieldSizesDemo from "../../../src/components/select-field-sizes-demo.tsx"; import SelectFieldCustomRenderDemo from "../../../src/components/select-field-custom-render-demo.tsx"; ## Overview SelectField is a simplified wrapper around the Select component that streamlines common use cases. It handles item rendering, label detection, and key generation automatically while maintaining full type safety. For more complex scenarios requiring custom sub-component composition, use the full Select component from `@px-ui/core`. ## Import ```tsx import { SelectField } from "@px-ui/forms"; ``` ## Usage ```tsx import { SelectField } from "@px-ui/forms"; import { useState } from "react"; export default function Example() { const [value, setValue] = useState(null); const items = [ { id: "apple", label: "Apple" }, { id: "banana", label: "Banana" }, { id: "orange", label: "Orange" }, { id: "mango", label: "Mango" }, { id: "grape", label: "Grape" }, ]; return ( ); } ``` ## Examples ### Multiple Selection Enable multiple item selection with the `multiple` prop. ```tsx import { SelectField } from "@px-ui/forms"; import { useState } from "react"; export default function Example() { const [value, setValue] = useState([]); const items = [ { id: "react", label: "React" }, { id: "vue", label: "Vue" }, { id: "angular", label: "Angular" }, { id: "svelte", label: "Svelte" }, { id: "solid", label: "Solid" }, ]; return ( ); } ``` ### Sizes Control the size of the select field using the `size` prop. ```tsx import { SelectField } from "@px-ui/forms"; import { useState } from "react"; export default function Example() { const [value, setValue] = useState(null); const items = [ { id: "sm", label: "Small" }, { id: "md", label: "Medium" }, { id: "lg", label: "Large" }, ]; return (
); } ``` ### Custom Rendering Use `renderLabel` and `renderOption` to customize how items are displayed. If not provided, SelectField automatically uses the `label` property from items. ```tsx import { SelectField } from "@px-ui/forms"; import { useState } from "react"; interface User { id: number; name: string; email: string; role: string; } export default function Example() { const [value, setValue] = useState(null); const users: User[] = [ { id: 1, name: "John Doe", email: "john@example.com", role: "Admin" }, { id: 2, name: "Jane Smith", email: "jane@example.com", role: "Editor" }, { id: 3, name: "Bob Johnson", email: "bob@example.com", role: "Viewer" }, { id: 4, name: "Alice Brown", email: "alice@example.com", role: "Editor" }, ]; return ( user.name} renderOption={(user) => (
{user.name} {user.email}
)} /> ); } ``` ## API Reference ### SelectField The main select field component that wraps the Select component from `@px-ui/core`. #### Custom Props | Prop | Type | Default | Description | | --------------------- | --------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `items` \* | `ReadonlyArray` | - | Array of items to display in the select dropdown | | `renderLabel` | `(item: TItem) => React.ReactNode` | - | Function to render the label in the trigger for the selected item. If not provided and item has a `label` property, it will be used automatically | | `renderOption` | `(item: TItem) => React.ReactNode` | - | Function to render each option in the dropdown. If not provided and item has a `label` property, it will be used automatically | | `placeholder` | `string` | - | Placeholder text when no value is selected | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant for the select trigger | | `widthVariant` | `'sm' \| 'md' \| 'lg' \| 'full'` | `'full'` | Width variant for the select trigger | | `contentWidthVariant` | `'trigger' \| 'full'` | `'trigger'` | Width variant for the dropdown content | | `triggerClassName` | `string` | - | Additional CSS classes for the trigger element | | `contentProps` | `Omit, 'children' \| 'widthVariant'>` | - | Additional props for Select.Content component | #### Inherited Props from Select.Root | Prop | Type | Default | Description | | -------------------- | ------------------------------------------- | ------- | --------------------------------------------------------------------------- | | `value` \* | `TItem \| TItem[] \| null` | - | The current selected value(s) | | `onValueChange` \* | `(value: TItem \| TItem[] \| null) => void` | - | Callback fired when the selected value changes | | `multiple` | `boolean` | `false` | Whether multiple items can be selected | | `disabled` | `boolean` | `false` | Whether the select is disabled | | `invalid` | `boolean` | `false` | Whether the select is in an invalid state | | `readOnly` | `boolean` | `false` | Whether the select is read-only | | `name` | `string` | - | Name attribute for form submission | | `isItemEqualToValue` | `(item: TItem, value: TItem) => boolean` | - | Custom equality function to compare items. By default, uses strict equality | | `inputRef` | `React.Ref` | - | Ref to the hidden input element used for form submission | *\* Required prop* ## Notes * SelectField automatically detects `label`, `id`, or `value` properties from items for key generation and display * For complex layouts or custom sub-component composition, use the full `Select` component from `@px-ui/core` * The component is fully type-safe and infers the item type from the `items` array * When using `multiple` selection, selected items are displayed as chips with a configurable max items (default: 2) # Select (/docs/components/select) import { SelectBasicDemo } from "../../../src/components/select-basic-demo"; import { SelectMultipleDemo } from "../../../src/components/select-multiple-demo"; import { SelectSizesDemo } from "../../../src/components/select-sizes-demo"; import { SelectDisabledDemo } from "../../../src/components/select-disabled-demo"; ## Overview The Select component provides a dropdown interface for choosing one or multiple values from a list of options. It features keyboard navigation, search functionality, smooth animations, and support for both single and multi-select modes. ## Import ```tsx import { Select } from "@px-ui/core"; ``` ## Usage ```tsx const [value, setValue] = useState(null); Apple Banana Orange ``` ## Examples ### Multiple Selection Enable multi-select mode to allow users to choose multiple options. ```tsx const [value, setValue] = useState([]); React Vue Angular ``` ### Sizes Select components support different sizes to match your design needs. ```tsx Option 1 Option 1 ``` ### Disabled Disable the select to prevent user interaction. ```tsx Apple Banana ``` ## Anatomy Components that make up `Select`: ### `Select.Root` The root container that manages select state and coordinates all select components. **Custom Props:** | Prop | Type | Default | Description | | --------------- | ------------------ | ------- | ----------------------------------------- | | `value` | `Value \| Value[]` | - | Selected value(s) | | `onValueChange` | `(value) => void` | - | Callback when selection changes | | `multiple` | `boolean` | `false` | Enable multi-select mode | | `disabled` | `boolean` | `false` | Whether the select is disabled | | `invalid` | `boolean` | `false` | Whether the select is in an invalid state | **Inherited Props:** Inherits all props from [Base UI Select.Root](https://base-ui.com/react/components/select#root) *** ### `Select.Trigger` Button that opens the select dropdown when clicked. **Custom Props:** | Prop | Type | Default | Description | | -------------- | ------------------------------- | ------------ | ----------------------------- | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the trigger button | | `widthVariant` | `"fit" \| "enforced" \| "full"` | `"enforced"` | Width behavior of the trigger | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Select.Trigger](https://base-ui.com/react/components/select#trigger) *** ### `Select.Value` Displays the currently selected value or placeholder text. **Custom Props:** | Prop | Type | Default | Description | | ------------- | ----------------------- | ------- | -------------------------------------- | | `placeholder` | `string` | - | Text to show when no value is selected | | `children` | `ReactNode \| function` | - | Custom render function for the value | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Select.Value](https://base-ui.com/react/components/select#value) *** ### `Select.Content` The dropdown content container with positioning and animations. **Custom Props:** | Prop | Type | Default | Description | | ----------------- | ---------------------------------- | ----------- | ---------------------------------- | | `widthVariant` | `"trigger" \| "fit" \| "enforced"` | `"trigger"` | Width behavior of the content | | `portalProps` | `object` | - | Props for the portal component | | `positionerProps` | `object` | - | Props for the positioner component | | `popupProps` | `object` | - | Props for the popup component | **Inherited Props:** Props are distributed to Base UI Portal, Positioner, and Popup components *** ### `Select.List` Container for select items, handles scrolling and keyboard navigation. **Inherited Props:** Inherits all props from [Base UI Select.List](https://base-ui.com/react/components/select#list) *** ### `Select.Item` Individual selectable option in the dropdown. **Custom Props:** | Prop | Type | Default | Description | | ----------- | --------- | ------- | ------------------------------ | | `value` | `any` | - | Value of this option | | `disabled` | `boolean` | `false` | Whether the option is disabled | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Select.Item](https://base-ui.com/react/components/select#item) *** ### `Select.MultiItem` Item component for multi-select mode with checkbox indicator. **Custom Props:** | Prop | Type | Default | Description | | ----------- | --------- | ------- | ------------------------------ | | `value` | `any` | - | Value of this option | | `disabled` | `boolean` | `false` | Whether the option is disabled | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Select.Item](https://base-ui.com/react/components/select#item) *** ### `Select.MultiSelectedValue` Helper component to display selected values in multi-select mode. **Custom Props:** | Prop | Type | Default | Description | | --------------- | -------- | ------- | ------------------------------------------------------- | | `selectedValue` | `any[]` | - | Array of selected values | | `maxItems` | `number` | - | Maximum number of items to display before showing count | *** ## API Reference See the [Anatomy](#anatomy) section above for detailed component props. # Separator (/docs/components/separator) import { SeparatorHorizontalDemo } from "../../../src/components/separator-horizontal-demo"; import { SeparatorVerticalDemo } from "../../../src/components/separator-vertical-demo"; import { SeparatorDecorativeDemo } from "../../../src/components/separator-decorative-demo"; ## Overview The Separator component provides a visual divider to separate content sections in your interface. It supports both horizontal and vertical orientations with proper ARIA attributes for accessibility, and can be marked as decorative when used purely for visual styling. ## Import ```tsx import { Separator } from "@px-ui/core"; ``` ## Usage ```tsx

Profile Settings

Manage your account preferences

Account
Privacy
Security
``` ## Examples ### Vertical Orientation Use vertical separators to divide content horizontally, such as in navigation menus or toolbars. ```tsx
Profile
Settings
Help
Logout
``` ### Decorative vs Semantic By default, separators are semantic (announced by screen readers). Use `decorative` when the separator is purely visual and shouldn't be announced. ```tsx {/* Semantic separator - announced by screen readers */} {/* Decorative separator - not announced by screen readers */} ``` ## API Reference ### Separator A visual divider component with configurable orientation and semantic behavior. | Prop | Type | Default | Description | | ------------- | ---------------------------- | ------------ | ---------------------------------------------------------------------------------------------- | | `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Direction of the separator line | | `decorative` | `boolean` | `false` | When true, sets `role="none"` to hide from screen readers. When false, uses `role="separator"` | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from native HTML `div` element. **Accessibility:** * Non-decorative separators use `role="separator"` and include `aria-orientation` for vertical separators * Decorative separators use `role="none"` and are hidden from assistive technologies # Spinner (/docs/components/spinner) import { SpinnerSizesDemo } from "../../../src/components/spinner-sizes-demo"; import { SpinnerWithTextDemo } from "../../../src/components/spinner-with-text-demo"; import { SpinnerLoadingDemo } from "../../../src/components/spinner-loading-demo"; ## Overview The Spinner component provides an animated loading indicator to show users that content is being loaded or an action is being processed. It includes proper ARIA attributes for screen readers and supports three size variants. ## Import ```tsx import { Spinner } from "@px-ui/core"; ``` ## Usage ```tsx ``` ## Examples ### With Text Combine the Spinner with text labels to provide context about what's loading. ```tsx
Loading...
Processing your request...
Please wait
``` ### Loading States Use the Spinner in common loading state scenarios like content areas and button loading states. ```tsx
Loading content...
``` ## API Reference ### Spinner An animated loading indicator with size customization and accessibility support. | Prop | Type | Default | Description | | ----------- | -------------------------------- | --------- | ------------------------------------------------------------ | | `size` | `"small" \| "medium" \| "large"` | `"small"` | Size of the spinner (small: 16px, medium: 24px, large: 32px) | | `className` | `string` | - | Additional CSS classes | **Accessibility:** The Spinner includes `role="status"` and `aria-label="Loading"` for screen reader support. # Switch (/docs/components/switch) import { SwitchBasicDemo } from "../../../src/components/switch-basic-demo"; import { SwitchSizesDemo } from "../../../src/components/switch-sizes-demo"; import { SwitchWithLabelsDemo } from "../../../src/components/switch-with-labels-demo"; import { SwitchDisabledDemo } from "../../../src/components/switch-disabled-demo"; ## Overview The Switch component provides a toggle control for binary on/off states with smooth sliding animations. It supports multiple sizes, keyboard accessibility, and clear visual feedback for checked, unchecked, and disabled states. ## Import ```tsx import { Switch } from "@px-ui/core"; ``` ## Usage ```tsx
``` ## Examples ### Sizes The Switch component supports three size variants to match different interface contexts. ```tsx ``` ### With Labels Switches are commonly paired with labels to describe what they control. Always use a label for accessibility. ```tsx
``` ### Disabled State Switches can be disabled in either the on or off state. ```tsx ``` ## API Reference ### Switch A toggle control component with smooth animations and multiple size options. | Prop | Type | Default | Description | | ----------- | --------------------------- | ----------- | ----------------------------------------------------------- | | `size` | `"sm" \| "lg" \| undefined` | `undefined` | Size of the switch. When undefined, renders at default size | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Switch.Root](https://base-ui.com/react/components/switch#root) including `checked`, `defaultChecked`, `onCheckedChange`, `disabled`, `required`, etc. # Tabs (/docs/components/tabs) import { TabsBasicDemo } from "../../../src/components/tabs-basic-demo"; import { TabsUnderlineDemo } from "../../../src/components/tabs-underline-demo"; import { TabsWithIconsDemo } from "../../../src/components/tabs-with-icons-demo"; import { TabsContentDemo } from "../../../src/components/tabs-content-demo"; import { TabsDisabledDemo } from "../../../src/components/tabs-disabled-demo"; ## Overview The Tabs component organizes content into multiple sections, allowing users to switch between them without leaving the page. It features an animated underline indicator that smoothly transitions between active tabs. ## Import ```tsx import { Tabs } from "@px-ui/core"; ``` ## Usage ```tsx Account Password Notifications

Manage your account settings and preferences.

Change your password and security settings.

Configure how you receive notifications.

 ``` ## Examples ### Underline Variant The Tabs component uses an underline style by default, with a smooth animated indicator that follows the active tab. ```tsx Posts Comments Likes Shares

Your published posts and articles.

 {/* Other content panels... */} ``` ### With Icons Enhance tab triggers with icons to provide visual context for each section. ```tsx Overview Analytics Settings

Dashboard overview and key metrics.

 {/* Other content panels... */} ``` ### Rich Content Tabs can contain complex content including forms, data displays, and interactive elements. ```tsx Profile Security
``` ### Disabled Tabs Disable individual tabs to prevent user interaction with unavailable sections. ```tsx Available Coming Soon Maintenance

This feature is currently available.

 ``` ## Anatomy Components that make up `Tabs`: ### `Tabs.Root` The root container that manages tab state and coordination between triggers and content panels. **Custom Props:** | Prop | Type | Default | Description | | ----------- | ------------- | ------------- | --------------------------------- | | `variant` | `"underline"` | `"underline"` | Visual style variant for the tabs | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Tabs.Root](https://base-ui.com/react/components/tabs#root) *** ### `Tabs.List` Container for tab triggers, displays the tab navigation bar with the animated indicator. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Tabs.List](https://base-ui.com/react/components/tabs#list) *** ### `Tabs.Trigger` Individual tab button that activates its corresponding content panel when clicked. **Custom Props:** | Prop | Type | Default | Description | | ----------- | --------- | ------- | -------------------------------------------- | | `value` | `string` | - | Unique identifier matching the content panel | | `disabled` | `boolean` | `false` | Whether the tab is disabled | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Tabs.Tab](https://base-ui.com/react/components/tabs#tab) *** ### `Tabs.Content` Content panel associated with a specific tab trigger, displayed when its tab is active. **Custom Props:** | Prop | Type | Default | Description | | ----------- | -------- | ------- | -------------------------------------- | | `value` | `string` | - | Unique identifier matching the trigger | | `className` | `string` | - | Additional CSS classes | **Inherited Props:** Inherits all props from [Base UI Tabs.Panel](https://base-ui.com/react/components/tabs#panel) *** ## API Reference See the [Anatomy](#anatomy) section above for detailed component props. # Textarea (/docs/components/textarea) import { TextareaBasicDemo } from "../../../src/components/textarea-basic-demo"; import { TextareaSizesDemo } from "../../../src/components/textarea-sizes-demo"; import { TextareaInvalidDemo } from "../../../src/components/textarea-invalid-demo"; ## Overview The Textarea component provides a styled multi-line text input field with support for different sizes, width behaviors, and validation states. It includes automatic styling for focus, disabled, and error states, with proper accessibility attributes. ## Import ```tsx import { Textarea } from "@px-ui/core"; ``` ## Usage ```tsx