Câmp

Prezentare generală

Utilizați Field pentru a grupa un control cu eticheta sa accesibilă și textul ajutător. Componente precum Input se integrează direct cu câmpul.

Utilizare

import { Field, Input } from 'twenty-ui/primitives/input';

export const EmailField = () => (
  <Field.Root name="email" validationMode="onBlur">
    <Field.Label>Work email</Field.Label>
    <Input type="email" required placeholder="you@example.com" />
    <Field.Description>
      We send account updates to this address.
    </Field.Description>
    <Field.Error match="valueMissing">Enter your email address.</Field.Error>
    <Field.Error match="typeMismatch">Enter a valid email address.</Field.Error>
  </Field.Root>
);

Field.Root gestionează numele controlului, starea de dezactivare și validitatea acestuia. Field.Label și Field.Description își conectează conținutul la control. Setați momentul validării cu validationMode; utilizați validate pentru validare personalizată.

Anatomie internă a componentelor?

Plasați un control și componentele sale auxiliare în Field.Root. Această structură arată un câmp construit cu componenta stilizată Input.

Field.Root
├── Field.Label
├── Input
├── Field.Description
└── Field.Error

Parte	Cerință	Scop
`Root`	Obligatoriu	Partajează numele, starea dezactivată și validarea cu controlul.
`Item`	Opțional pentru grupuri	Asociază fiecărui buton radio sau fiecărei casete de selectare propria etichetă și descriere.
`Label`	Recomandat	Furnizează o etichetă vizibilă asociată. Este întotdeauna necesar un nume accesibil.
`Input` sau un alt control integrat	Obligatoriu	Primește datele introduse de utilizator și se conectează la câmp.
`Control`	Control alternativ	Furnizează o intrare nestilizată atunci când nu utilizați un control integrat.
`Description`	Opțional	Adaugă text de ajutor persistent asociat cu controlul.
`Eroare`	Opțional	Afișează feedback pentru o stare de validare corespunzătoare.
`Validity`	Opțional	Expune validitatea printr-o funcție de randare pentru copii.

Input și Textarea se integrează deja cu câmpul. Plasați-le direct în Root; acestea furnizează singure comportamentul de control. Controalele compuse, precum Select, își păstrează propria rădăcină și propriile componente în interiorul câmpului.

Erori externe

Utilizați invalid atunci când aplicația dvs. gestionează starea de eroare. Un match explicit face vizibil mesajul de eroare.

import { Field, Input } from 'twenty-ui/primitives/input';

type UsernameFieldProps = { error?: string };

export const UsernameField = ({ error }: UsernameFieldProps) => (
  <Field.Root name="username" invalid={Boolean(error)}>
    <Field.Label>Username</Field.Label>
    <Input autoComplete="username" />
    <Field.Error match={Boolean(error)}>{error}</Field.Error>
  </Field.Root>
);

Păstrați mesajele de eroare ușor de acționat și oferiți o etichetă vizibilă chiar și atunci când controlul are un substituent.

Controale grupate

Folosește Field.Item într-un grup de butoane radio sau de casete de selectare pentru a asocia fiecare opțiune cu propria etichetă și descriere. Păstrează eticheta grupului în afara elementelor. Un element poate fi dezactivat independent; un Field.Root dezactivat dezactivează fiecare element.

import { Field, Radio, RadioGroup } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';

export const NotificationsField = () => (
  <Field.Root name="notifications">
    <Field.Label>Notifications</Field.Label>
    <RadioGroup defaultValue="important" style={{ gap: 16, marginTop: 12 }}>
      <Field.Item style={{ display: 'flex', alignItems: 'start', gap: 12 }}>
        <Radio value="important" />
        <Text>
          <Field.Label>Important updates</Field.Label>
          <Field.Description>
            Only messages that need your attention
          </Field.Description>
        </Text>
      </Field.Item>
      <Field.Item style={{ display: 'flex', alignItems: 'start', gap: 12 }}>
        <Radio value="all" />
        <Text>
          <Field.Label>All updates</Field.Label>
          <Field.Description>Every change to your records</Field.Description>
        </Text>
      </Field.Item>
      <Field.Item
        disabled
        style={{ display: 'flex', alignItems: 'start', gap: 12 }}
      >
        <Radio value="digest" />
        <Text>
          <Field.Label>Daily digest</Field.Label>
          <Field.Description>Coming soon</Field.Description>
        </Text>
      </Field.Item>
    </RadioGroup>
  </Field.Root>
);

Integrare nativă și tipuri

Field păstrează momentul validării Base UI, validarea personalizată, valorile controlate și necontrolate ale controalelor și detaliile evenimentului de modificare a valorii. Validity expune rezultatul validării prin funcția sa children. Controalele integrate își păstrează comportamentul nativ al formularului. Root, Item, Label, Control, Description și Error transmit props native, refs și compoziția render. Elementele lor implicite sunt, respectiv, un div, div, label, input, paragraf și div. Validity nu redă propriul element. Importă FieldRootProps, FieldItemProps, FieldLabelProps, FieldControlProps, FieldDescriptionProps, FieldErrorProps și FieldValidityProps din twenty-ui/primitives/input pentru contractele corespunzătoare ale componentelor din amonte.

Proprietăți

Referința este generată din tipurile componentei publice. Atributele native, inclusiv numele accesibile și gestionarele de evenimente, sunt acceptate și pe părțile care redau elemente.

Field.Root

RefObject<FieldRootActions | null>

A ref to imperative actions.

validate: Validates the field when called.

string | ((state: FieldRootState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

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

boolean

implicit:"false"

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

boolean

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

string

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

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldRootState>

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.

CSSProperties | ((state: FieldRootState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

boolean

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

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".

number

implicit:"0"

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

"onBlur" | "onChange" | "onSubmit"

implicit:"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.

Field.Item

string | ((state: FieldItemState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

implicit:"false"

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

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldItemState>

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.

CSSProperties | ((state: FieldItemState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Field.Label

string | ((state: FieldLabelState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

implicit:"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.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldLabelState>

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.

CSSProperties | ((state: FieldLabelState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Field.Control

string | ((state: FieldControlState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

string | number | readonly string[]

The default value of the input. Use when uncontrolled.

((value: string, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)

Callback fired when the value changes. Use when controlled.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldControlState>

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.

CSSProperties | ((state: FieldControlState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Field.Description

string | ((state: FieldDescriptionState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldDescriptionState>

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.

CSSProperties | ((state: FieldDescriptionState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Field.Error

string | ((state: FieldErrorState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean | keyof ValidityState

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.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldErrorState>

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.

CSSProperties | ((state: FieldErrorState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Field.Validity

(state: FieldValidityState) => ReactNode

obligatoriu

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

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

Dezvoltatori

Aplicații

API

Autogazda

Contribuie

Biblioteca UI

Prezentare generală

Utilizare

Anatomie internă a componentelor?

Erori externe

Controale grupate

Integrare nativă și tipuri

Proprietăți

Field.Root

Field.Item

Field.Label

Field.Control

Field.Description

Field.Error

Field.Validity

​Prezentare generală

​Utilizare

​Anatomie internă a componentelor?

​Erori externe

​Controale grupate

​Integrare nativă și tipuri

​Proprietăți

​Field.Root

​Field.Item

​Field.Label

​Field.Control

​Field.Description

​Field.Error

​Field.Validity

Prezentare generală

Utilizare

Anatomie internă a componentelor?

Erori externe

Controale grupate

Integrare nativă și tipuri

Proprietăți

Field.Root

Field.Item

Field.Label

Field.Control

Field.Description

Field.Error

Field.Validity