Campo

Panoramica

Usa Field per raggruppare un controllo con la relativa etichetta accessibile e il testo di supporto. Componenti come Input si integrano direttamente con il campo.

Utilizzo

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 gestisce il nome del controllo, lo stato disabilitato e la validità. Field.Label e Field.Description collegano il loro contenuto al controllo. Imposta la tempistica della convalida con validationMode; usa validate per la convalida personalizzata.

Anatomia

Inserisci un controllo e le relative parti di supporto all’interno di Field.Root. Questo albero mostra un campo creato con il componente Input stilizzato.

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

Parte	Requisito	Scopo
`Root`	Obbligatorio	Condivide il nome, lo stato disabilitato e la convalida con il controllo.
`Item`	Facoltativo per i gruppi	Associa ogni pulsante di scelta o casella di controllo alla propria etichetta e descrizione.
`Label`	Consigliato	Fornisce un’etichetta visibile associata. Un nome accessibile è sempre obbligatorio.
`Input` o un altro controllo integrato	Obbligatorio	Riceve l’input dell’utente e si collega al campo.
`Control`	Controllo alternativo	Fornisce un input senza stile quando non utilizzi un controllo integrato.
`Description`	Facoltativo	Aggiunge testo di supporto persistente associato al controllo.
`Errore`	Facoltativo	Mostra feedback per uno stato di convalida corrispondente.
`Validity`	Facoltativo	Espone la validità tramite una funzione di rendering children.

Input e Textarea si integrano già con il campo. Inseriscili direttamente all’interno di Root; forniscono autonomamente il comportamento del controllo. I controlli composti come Select mantengono la propria radice e le proprie parti all’interno del campo.

Errori esterni

Usa invalid quando la tua applicazione gestisce lo stato di errore. Un match esplicito rende visibile il messaggio di errore.

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>
);

Mantieni i messaggi di errore orientati all’azione e fornisci un’etichetta visibile anche quando il controllo ha un segnaposto.

Controlli raggruppati

Usa Field.Item all’interno di un gruppo di pulsanti di opzione o caselle di controllo per associare ogni scelta alla relativa etichetta e descrizione. Mantieni l’etichetta del gruppo al di fuori degli elementi. Un elemento può essere disabilitato indipendentemente; un Field.Root disabilitato disabilita ogni elemento.

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>
);

Integrazione nativa e tipi

Field preserva la tempistica di convalida di Base UI, la convalida personalizzata, i valori dei controlli gestiti e non gestiti e i dettagli dell’evento di modifica del valore. Validity espone il risultato della convalida tramite la sua funzione children. I controlli integrati mantengono il loro comportamento nativo nei moduli. Root, Item, Label, Control, Description e Error inoltrano props native, refs e composizione render. I relativi elementi predefiniti sono rispettivamente un div, div, label, input, paragrafo e div. Validity non esegue il rendering del proprio elemento. Importa FieldRootProps, FieldItemProps, FieldLabelProps, FieldControlProps, FieldDescriptionProps, FieldErrorProps e FieldValidityProps da twenty-ui/primitives/input per i contratti delle parti upstream corrispondenti.

Props

Il riferimento è generato dai tipi di componenti pubblici. Gli attributi nativi, inclusi i nomi accessibili e i gestori di eventi, sono accettati anche nelle parti che eseguono il rendering di elementi.

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

predefinito:"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

predefinito:"0"

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

"onBlur" | "onChange" | "onSubmit"

predefinito:"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

predefinito:"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

predefinito:"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

obbligatorio

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

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

Sviluppatori

App

API

Auto-ospitazione

Contribuire

Libreria UI

Panoramica

Utilizzo

Anatomia

Errori esterni

Controlli raggruppati

Integrazione nativa e tipi

Props

Field.Root

Field.Item

Field.Label

Field.Control

Field.Description

Field.Error

Field.Validity

​Panoramica

​Utilizzo

​Anatomia

​Errori esterni

​Controlli raggruppati

​Integrazione nativa e tipi

​Props

​Field.Root

​Field.Item

​Field.Label

​Field.Control

​Field.Description

​Field.Error

​Field.Validity

Panoramica

Utilizzo

Anatomia

Errori esterni

Controlli raggruppati

Integrazione nativa e tipi

Props

Field.Root

Field.Item

Field.Label

Field.Control

Field.Description

Field.Error

Field.Validity