XiodUI
HomeDocs
OverviewComponentsStyling & CustomizationChangelog

Components

  • Accordion
  • Agent Steps
  • Alert
  • Alert Dialog
  • Aspect Ratio
  • Autocomplete
  • Avatar
  • Badge
  • Breadcrumb
  • Button
  • Button Group
  • Button Split
  • Calendar
  • Card
  • Carousel
  • Checkbox
  • Circular Progress
  • Collapsible
  • Color Picker
  • Combobox
  • Command
  • Context Menu
  • Copy To Clipboard
  • Corner Badge
  • Dashboard Grid
  • Date Picker
  • Dialog
  • Dot Matrix
  • Draggable
    Updated
  • Drawer
  • Empty
  • Field
  • Fieldset
  • File Upload
    Updated
  • Form
  • Frame
  • Gauge
  • Grid
  • Group
  • Input
  • Input Group
  • Input OTP
  • Input Payment
  • Input Phone
    Updated
  • Input Sensitive
  • Kbd
  • Kinetic Click
  • Label
  • List Box
    Updated
  • Loader
  • Marker
  • Menu
  • Menubar
  • Message
  • Meter
  • Morphic Toast
  • Navigation Menu
  • Number Field
  • Option Picker
  • Orb
  • Pagination
  • Popover
  • Preview Card
    Updated
  • Progress
  • Radio
  • Resizable
  • Ruler Picker
  • Scroll Area
  • Scroll Bar
  • Select
  • Separator
  • Sidebar
  • Skeleton
  • Slider
  • Sortable
  • Switch
  • Table
  • Tabs
  • Text
  • Textarea
  • Timeline
  • Toast
  • Toggle
  • Toggle Group
  • Toolbar
  • Tooltip
  • Waveform
  • Wheel Picker

Loading...

Preview Skeleton

Installation Skeleton

Usage Skeleton

API Reference Skeleton

Sponsors

Support the development of XiodUI and help us build the best component library on Earth.

+++
Sponsor on GitHub

Field

Previous: EmptyNext: Fieldset

A form field that ties a label, control, description and validation message together.

Preview

Loading Preview...

Installation

bun add xiod-ui

Usage

Imports

1import {2  Field,3  FieldControl,4  FieldDescription,5  FieldError,6  FieldItem,7  FieldLabel,8  FieldValidity9} from "xiod-ui/field";

Anatomy

1<Field>2  <FieldLabel />3  <FieldDescription />4</Field>

API Reference

Detailed documentation of properties and options.

Field

Accepts className, style and render, plus every native attribute of the element it renders.

PropTypeDefaultDescription
actionsRef
RefObject<FieldRootActions | null>
–

A ref to imperative actions.

  • validate: Validates the field when called.
EmptyFieldset
dirty
boolean
–

Whether the field's value has been changed from its initial value. Useful when the field state is controlled by an external library.

disabled
boolean
false

Whether the component should ignore user interaction. Takes precedence over the disabled prop on the <Field.Control> component.

invalid
boolean
–

Whether the field is invalid. Useful when the field state is controlled by an external library.

name
string
–

Identifies the field when a form is submitted. Takes precedence over the name prop on the <Field.Control> component.

touched
boolean
–

Whether the field has been touched. Useful when the field state is controlled by an external library.

validate
((value: unknown, formValues: Form.Values) => string | string[] | null | void | Promise<string | string[] | null | void>)
–

A function for custom validation. Return a string or an array of strings with the error message(s) if the value is invalid. Returning nothing, null, an empty string, or an empty array means the value is valid. Asynchronous functions are supported, but they do not prevent form submission when using validationMode="onSubmit".

validationDebounceTime
number
0

How long to wait between validate callbacks if validationMode="onChange" is used. Specified in milliseconds.

validationMode
"onBlur"|"onChange"|"onSubmit"
'onSubmit'

Determines when the field should be validated. This takes precedence over the validationMode prop on <Form>.

  • onSubmit: triggers validation when the form is submitted, and re-validates on change after submission.
  • onBlur: triggers validation when the control loses focus.
  • onChange: triggers validation on every change to the control value.

FieldControl

Accepts className, style and render, plus every native attribute of the element it renders.

PropTypeDefaultDescription
defaultValue
string | number | readonly string[]
–

The value the input starts with, when it isn't controlled.

onValueChange
((value: string, eventDetails: FieldControl.ChangeEventDetails) => void)
–

Callback fired when the value changes. Use when controlled.

FieldDescription

Accepts className, style and render, plus every native attribute of the element it renders.

FieldError

Accepts className, style and render, plus every native attribute of the element it renders.

PropTypeDefaultDescription
match
boolean|keyof ValidityState
–

Determines whether to show the error message according to the field's [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState). Specifying true will always show the error message, and lets external libraries control the visibility.

FieldItem

Accepts className, style and render, plus every native attribute of the element it renders.

PropTypeDefaultDescription
disabled
boolean
false

Whether the wrapped control should ignore user interaction. The disabled prop on <Field.Root> takes precedence over this.

FieldLabel

Accepts className, style and render, plus every native attribute of the element it renders.

PropTypeDefaultDescription
nativeLabel
boolean
true

Whether the component renders a native <label> element when replacing it via the render prop. Set to false if the rendered element is not a label (for example, <div>).

This is useful to avoid inheriting label behaviors on <button> controls (such as <Select.Trigger> and <Combobox.Trigger>), including avoiding :hover on the button when hovering the label, and preventing clicks on the label from firing on the button.

FieldValidity

PropTypeDefaultDescription
childrenReq
(state: FieldValidityState) => ReactNode
–

A function that accepts the field validity state as an argument.

``jsx <Field.Validity> {(validity) => { return <div>...</div> }} </Field.Validity> ``