Form and Input Primitives
Relevant source files
The following files were used as context for generating this wiki page:
Form and Input Primitives provide the foundational interactive elements for user data entry within the HX-UI library. These components are built primarily upon Radix UI to ensure accessibility (ARIA compliance), consistent keyboard navigation, and robust state management. The primitives serve as the "Basic Parts" of the library, emphasizing technical precision such as non-scaling strokes for responsive design and specialized CSS for layout stability.
The system differentiates between low-level primitives/ (e.g., Switch, Slider, Select) and higher-level layout/ fields (e.g., SelectField, InputField). While the primitives handle core behavior and styling, the layout fields wrap these primitives into consistent patterns for specific application contexts like settings pages.
Sources: src/index.ts:7-13, README.md:15-28, src/layout/SettingsFormFields.tsx
Core Input Primitives
Textarea and Input
The Textarea component provides a multi-line text entry field. It utilizes the field-sizing-content CSS property to allow the browser to automatically adjust the height based on content, avoiding manual DOM manipulation. It maintains a minimum height of 4 lines (min-h-16) to ensure visual consistency when empty.
Sources: src/primitives/textarea.tsx:11-20
Selection and Toggle Controls
Select and Switch components leverage Radix UI primitives to provide accessible dropdowns and boolean toggles. The Switch component specifically uses a SwitchPrimitives.Thumb for the sliding visual indicator. The Slider primitive allows for numerical range selection, utilizing SliderPrimitives.Range and SliderPrimitives.Thumb.
Sources: src/primitives/select.tsx, src/primitives/switch.tsx, src/primitives/slider.tsx
Selection Logic Flow
The following diagram illustrates the component composition for the Select primitive:
The Select component uses a Portal to render the dropdown content, ensuring it appears above other layout elements without z-index conflicts.
Sources: src/primitives/select.tsx:18-100
Date and Time Selection
TimePicker Architecture
The TimePicker is a custom implementation that avoids the native <input type="time"> to maintain layout stability across different browsers. It consists of two coordinated numerical inputs for hours (0-23) and minutes (0-59).
Sources: src/primitives/time-picker.tsx:9-18
Key behaviors include:
- Controlled Input: Allows intermediate states (e.g., "0") during typing but validates on blur (e.g., "7" becomes "07").
- Clamping: Automatically restricts values to valid ranges (0-23 for hours, 0-59 for minutes) rather than throwing errors.
- Visual Consistency: Removes native spinners to match standard
Inputsizing.
Sources: src/primitives/time-picker.tsx:20-24
Calendar and DatePicker
The Calendar component is built on react-day-picker and provides the visual grid for date selection. The DatePicker component wraps the Calendar inside a Popover, allowing users to select dates via a toggleable interface.
Sources: src/primitives/calendar.tsx, src/primitives/date-picker.tsx
Layout-Specific Fields
The library provides specialized wrappers in src/layout/SettingsFormFields.tsx to standardize input presentation in settings rows.
| Component | Wrapped Primitive | Context/Usage |
|---|---|---|
InputField | Input | Standard text input in settings rows. |
SelectField | Select | Dropdown selection with defined options. |
TextareaField | Textarea | Multi-line text entry in settings rows. |
These fields typically accept standard props and ensure that triggers like SelectTrigger maintain consistent styling (e.g., h-8, w-40).
Sources: src/layout/SettingsFormFields.tsx:5-30
Technical Specifications
Input Styling Tokens
Inputs use CSS variables defined in tokens.css to handle theming.
| Token | Description | Value (Dark Mode) |
|---|---|---|
--input | Background color for input elements | rgb(48, 51, 64) |
--ring | Focus ring color | rgb(129, 132, 248) |
--border | Default border color | rgb(42, 45, 56) |
--fs-sm | Small font size for input labels/text | 12px |
--fs-base | Base font size | 13px |
Sources: src/tokens.css:26-31, src/tokens.css:127-131
Shared Logic and Utilities
Most input primitives utilize a shared cn utility for tailwind class merging and utils.ts for common types. This ensures that custom class names passed via props do not conflict with the library's base styles.
Sources: src/primitives/input.tsx:10-15, src/primitives/select.tsx:140
Form and Input Primitives in HX-UI prioritize functional reliability and visual consistency by wrapping standardized Radix behaviors in custom-styled containers that adhere to the project's design tokens.