@fayegram-ai/faye-ui/controls/field
Public exports and dependency-resolved component properties, with usage and rendering guidance.
Import
import { Field } from '@fayegram-ai/faye-ui/controls/field';Usage and behavior guide · API JSON
This entry declares a client boundary. Follow the rendering guide for framework integration.
Public exports
| Name | Kind | Resolved declaration type |
|---|---|---|
Field | value | { readonly Control: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react").FieldControlProps, "ref"> & import("react").RefAttributes<HTMLElement>>; readonly Validity: import("react").FC<import("@base-ui/react").FieldValidityProps>; readonly Root: { (input: Omit<import("@base-ui/react").FieldRootProps, "ref"> & import("react").RefAttributes<HTMLDivElement> & { variants?: { readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "size"> | undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "tone"> | undefined; } | undefined; }): import("react").ReactElement; displayName: string; }; readonly Label: { (input: Omit<import("@base-ui/react").FieldLabelProps, "ref"> & import("react").Ref… (full type in API JSON) |
Field
Public component; use the linked family guide for complete composition and behavior.
Dependency-resolved declaration properties. Common React/native HTML attributes are omitted from the table; use the full declaration and React/native references. Generic and union restrictions remain authoritative in TypeScript.
Field.Control
| Property | Required | Type | Meaning |
|---|---|---|---|
className | No | string | ((state: FieldControlState) => string | undefined) | undefined | CSS class applied to the element, or a function that returns a class based on the component's state. |
defaultValue | No | string | number | readonly string[] | undefined | See the usage contract and declaration. |
onValueChange | No | ((value: string, eventDetails: FieldControl.ChangeEventDetails) => void) | undefined | Callback fired when the value changes. Use when controlled. |
render | No | ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldControlState> | 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 | No | CSSProperties | ((state: FieldControlState) => React.CSSProperties | undefined) | undefined | Style applied to the element, or a function that returns a style object based on the component's state. |
Field.Validity
| Property | Required | Type | Meaning |
|---|---|---|---|
children | Yes | (state: FieldValidityState) => React.ReactNode | A function that accepts the field validity state as an argument. ``jsx <Field.Validity> {(validity) => { return <div>...</div> }} </Field.Validity> |
Field.Root
| Property | Required | Type | Meaning |
|---|---|---|---|
actionsRef | No | RefObject<FieldRootActions | null> | undefined | A ref to imperative actions. - validate: Validates the field when called. |
className | No | string | ((state: FieldRootState) => string | undefined) | undefined | CSS class applied to the element, or a function that returns a class based on the component's state. |
dirty | No | 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. |
disabled | No | boolean | undefined | Whether the component should ignore user interaction. Takes precedence over the disabled prop on the <Field.Control> component. |
invalid | No | boolean | undefined | Whether the field is invalid. Useful when the field state is controlled by an external library. |
name | No | string | undefined | Identifies the field when a form is submitted. Takes precedence over the name prop on the <Field.Control> component. |
render | No | ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldRootState> | 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 | No | CSSProperties | ((state: FieldRootState) => React.CSSProperties | undefined) | undefined | Style applied to the element, or a function that returns a style object based on the component's state. |
touched | No | boolean | undefined | Whether the field has been touched. Useful when the field state is controlled by an external library. |
validate | No | ((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". |
validationDebounceTime | No | number | undefined | How long to wait between validate callbacks if validationMode="onChange" is used. Specified in milliseconds. |
validationMode | No | FormValidationMode | 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. |
variants | No | { readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "size"> | undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "tone"> | undefined; } | undefined | See the usage contract and declaration. |
Field.Label
| Property | Required | Type | Meaning |
|---|---|---|---|
className | No | string | ((state: FieldLabelState) => string | undefined) | undefined | CSS class applied to the element, or a function that returns a class based on the component's state. |
nativeLabel | No | 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. |
render | No | ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldLabelState> | 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 | No | CSSProperties | ((state: FieldLabelState) => React.CSSProperties | undefined) | undefined | Style applied to the element, or a function that returns a style object based on the component's state. |
variants | No | { readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "size"> | undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "tone"> | undefined; } | undefined | See the usage contract and declaration. |
Field.Description
| Property | Required | Type | Meaning |
|---|---|---|---|
className | No | string | ((state: FieldDescriptionState) => string | undefined) | undefined | CSS class applied to the element, or a function that returns a class based on the component's state. |
render | No | ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldDescriptionState> | 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 | No | CSSProperties | ((state: FieldDescriptionState) => React.CSSProperties | undefined) | undefined | Style applied to the element, or a function that returns a style object based on the component's state. |
variants | No | { readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "size"> | undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "tone"> | undefined; } | undefined | See the usage contract and declaration. |
Field.Error
| Property | Required | Type | Meaning |
|---|---|---|---|
className | No | string | ((state: FieldErrorState) => string | undefined) | undefined | CSS class applied to the element, or a function that returns a class based on the component's state. |
match | No | boolean | keyof ValidityState | undefined | Determines whether to show the error message according to the field's ValidityState. Specifying true will always show the error message, and lets external libraries control the visibility. |
render | No | ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldErrorState> | 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 | No | CSSProperties | ((state: FieldErrorState) => React.CSSProperties | undefined) | undefined | Style applied to the element, or a function that returns a style object based on the component's state. |
variants | No | { readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "size"> | undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "tone"> | undefined; } | undefined | See the usage contract and declaration. |
Defaults and customization
Descriptor defaults: {"size":"md","tone":"neutral"}. Parts: root, label, description, error. Explicit instance props take precedence over configured defaults.
Use semantic tokens, public part hooks and customization sheets. Keep visual configuration separate from application state.
State, events and accessibility
For interactive controls, pair a controlled value/open prop with its corresponding change callback; default props initialize uncontrolled state. Keep application validation and submission policy explicit. Name controls with visible labels, name icon-only actions on the button, and preserve focus and dismissal behavior when replacing parts. Use native form names and submit/reset types where supported. See the usage guide for component-specific behavior and live examples.
Declaration authority
Generated from packages/faye-ui/dist/controls/field.d.ts after the semantic package build. Common native/React attributes are intentionally omitted from property tables. Generic overloads, discriminated unions and complete inherited attributes remain authoritative in installed TypeScript declarations. React DOM attributes and Base UI component contracts describe the inherited foundations.