Field

On this page

Report title

Use a short, specific title.

Audience

The people this report is written for.

One label, description and validation context for a composed control.

Code

import { Field } from "@bosunkit/components/field";
import { Input } from "@bosunkit/components/input";
import { FormField } from "@bosunkit/components/form-field";
import type { ReactElement } from "react";
export const description: string =
  "Primitive parts and the outlined recipe connect labels and instructions to their controls through the same field semantics.";
export default function Showcase(): ReactElement {
  return (
    <div style={{ display: "grid", gap: "var(--space-xl)" }}>
      <Field.Root>
        <Field.Label>Report title</Field.Label>
        <Input defaultValue="Weekly delivery" />
        <Field.Description>Use a short, specific title.</Field.Description>
      </Field.Root>
      <FormField label="Audience" appearance="outlined" hint="The people this report is written for." required>
        <Input defaultValue="Engineering team" />
      </FormField>
    </div>
  );
}

01Names describe behaviorUse the primitive for custom composition and a named recipe for an assembled control.

02One state contractControlled values, defaults and change callbacks follow Base UI; event details keep their reason and cancellation.

03Composition keeps semanticsA render target forwards its ref and every received DOM prop so keyboard interaction and accessible names survive.

Composition

Import { Field } from @bosunkit/components/field. Named parts follow Base UI Field. Each part retains the upstream render, ref, DOM props, state attributes and event contracts. The kit supplies its typography, surfaces and scoped overlay presentation.

Examples

Custom composition

Report title

Use a short, specific title.

Audience

The people this report is written for.

Primitive parts and the outlined recipe connect labels and instructions to their controls through the same field semantics.

Code

import { Field } from "@bosunkit/components/field";
import { Input } from "@bosunkit/components/input";
import { FormField } from "@bosunkit/components/form-field";
import type { ReactElement } from "react";
export const description: string =
  "Primitive parts and the outlined recipe connect labels and instructions to their controls through the same field semantics.";
export default function Showcase(): ReactElement {
  return (
    <div style={{ display: "grid", gap: "var(--space-xl)" }}>
      <Field.Root>
        <Field.Label>Report title</Field.Label>
        <Input defaultValue="Weekly delivery" />
        <Field.Description>Use a short, specific title.</Field.Description>
      </Field.Root>
      <FormField label="Audience" appearance="outlined" hint="The people this report is written for." required>
        <Input defaultValue="Engineering team" />
      </FormField>
    </div>
  );
}

Props

Prop	Type	Default	Description
disabled	boolean \| undefined	–	Whether the component should ignore user interaction. Takes precedence over the `disabled` prop on the `<Field.Control>` component.
name	string \| undefined	–	Identifies the field when a form is submitted. Takes precedence over the `name` prop on the `<Field.Control>` component.
validate	((value: unknown, formValues: Form.Values) => string \| string[] \| null \| void \| Promise<string \| string[] \| null \| void>) \| undefined	–	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"`.
validationMode	Form.ValidationMode \| undefined	–	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.
validationDebounceTime	number \| undefined	–	How long to wait between `validate` callbacks if `validationMode="onChange"` is used. Specified in milliseconds.
invalid	boolean \| undefined	–	Whether the field is invalid. Useful when the field state is controlled by an external library.
dirty	boolean \| undefined	–	Whether the field's value has been changed from its initial value. Useful when the field state is controlled by an external library.
touched	boolean \| undefined	–	Whether the field has been touched. Useful when the field state is controlled by an external library.
actionsRef	React.RefObject<FieldRoot.Actions \| null> \| undefined	–	A ref to imperative actions. - `validate`: Validates the field when called.
className	string \| ((state: State) => string \| undefined) \| undefined	–	CSS class applied to the element, or a function that returns a class based on the component's state.
render	React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> \| undefined	–	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) \| undefined	–	Style applied to the element, or a function that returns a style object based on the component's state.

Also takes every attribute of Primitive.Root.Props.

Prop	Type	Default	Description
nativeLabel	boolean \| undefined	–	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.
className	string \| ((state: State) => string \| undefined) \| undefined	–	CSS class applied to the element, or a function that returns a class based on the component's state.
render	React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> \| undefined	–	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) \| undefined	–	Style applied to the element, or a function that returns a style object based on the component's state.

Also takes every attribute of Primitive.Label.Props.

Prop	Type	Default	Description
onValueChange	((value: string, eventDetails: FieldControl.ChangeEventDetails) => void) \| undefined	–	Callback fired when the `value` changes. Use when controlled.
defaultValue	React.ComponentProps<'input'>['defaultValue'] \| undefined	–
className	string \| ((state: State) => string \| undefined) \| undefined	–	CSS class applied to the element, or a function that returns a class based on the component's state.
render	React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> \| undefined	–	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) \| undefined	–	Style applied to the element, or a function that returns a style object based on the component's state.

Also takes every attribute of Primitive.Control.Props.

Prop	Type	Default	Description
className	string \| ((state: State) => string \| undefined) \| undefined	–	CSS class applied to the element, or a function that returns a class based on the component's state.
render	React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> \| undefined	–	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) \| undefined	–	Style applied to the element, or a function that returns a style object based on the component's state.

Also takes every attribute of Primitive.Description.Props.

Prop	Type	Default	Description
match	boolean \| keyof ValidityState \| undefined	–	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.
className	string \| ((state: State) => string \| undefined) \| undefined	–	CSS class applied to the element, or a function that returns a class based on the component's state.
render	React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> \| undefined	–	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) \| undefined	–	Style applied to the element, or a function that returns a style object based on the component's state.

Also takes every attribute of Primitive.Error.Props.

Report title

Use a short, specific title.

Audience

The people this report is written for.

Compose labeled parts and preserve their ref and DOM props.

Don't

Use the named parts for keyboard and focus behavior.

Do not replace semantic controls with clickable generic elements or discard event details.

Component API: naming, state, composition and compatibility.
Interaction states: focus, disabled and selected presentation.
Form field: the assembled label and validation recipe.

Composition

Examples

Custom composition

Props

Related