Campo

Resumen

Usa Field para agrupar un control con su etiqueta accesible y texto de ayuda. Los componentes como Input se integran directamente con el campo.

”Uso”

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 gestiona el nombre del control, el estado deshabilitado y la validez. Field.Label y Field.Description conectan su contenido con el control. Establece el momento de la validación con validationMode; usa validate para la validación personalizada.

Anatomía

Coloque un control y sus partes de apoyo dentro de Field.Root. Este árbol muestra un campo creado con el componente Input con estilos.

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

Parte	Requisito	Propósito
`Root`	Obligatorio	Comparte el nombre, el estado deshabilitado y la validación con el control.
`Elemento`	Opcional para grupos	Asocia cada botón de opción o casilla de verificación con su propia etiqueta y descripción.
`Label`	Recomendado	Proporciona una etiqueta visible asociada. Siempre se requiere un nombre accesible.
`Input` u otro control integrado	Obligatorio	Recibe la entrada del usuario y se conecta al campo.
`Control`	Control alternativo	Proporciona una entrada sin estilos cuando no usa un control integrado.
`Description`	Opcional	Agrega texto de ayuda persistente asociado al control.
`Error`	Opcional	Muestra comentarios para un estado de validación coincidente.
`Validity`	Opcional	Expone la validez mediante una función de renderizado de elementos secundarios.

Input y Textarea ya se integran con el campo. Colóquelos directamente dentro de Root; ellos mismos proporcionan el comportamiento del control. Los controles compuestos como Select mantienen su propio elemento raíz y partes dentro del campo.

Errores externos

Usa invalid cuando tu aplicación gestiona el estado de error. Un match explícito hace visible el mensaje de error.

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

Mantén los mensajes de error orientados a la acción y proporciona una etiqueta visible incluso cuando el control tenga un marcador de posición.

Controles agrupados

Use Field.Item dentro de un grupo de botones de opción o casillas de verificación para asociar cada opción con su propia etiqueta y descripción. Mantenga la etiqueta del grupo fuera de los elementos. Un elemento puede deshabilitarse de forma independiente; un Field.Root deshabilitado deshabilita todos los elementos.

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

Integración nativa y tipos

Field conserva el tiempo de validación de Base UI, la validación personalizada, los valores de controles controlados y no controlados, y los detalles del evento de cambio de valor. Validity expone el resultado de la validación mediante su función de elementos secundarios. Los controles integrados conservan su comportamiento de formulario nativo. Root, Item, Label, Control, Description y Error reenvían las props y refs nativas, así como la composición de render. Sus elementos predeterminados son un div, div, label, input, paragraph y div, respectivamente. Validity no representa su propio elemento. Importe FieldRootProps, FieldItemProps, FieldLabelProps, FieldControlProps, FieldDescriptionProps, FieldErrorProps y FieldValidityProps desde twenty-ui/primitives/input para los contratos correspondientes de las partes ascendentes.

”Props”

La referencia se genera a partir de los tipos de componentes públicos. Los atributos nativos, incluidos los nombres accesibles y los controladores de eventos, también se aceptan en las partes que renderizan elementos.

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

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

predeterminado:"0"

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

"onBlur" | "onChange" | "onSubmit"

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

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

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

requerido

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

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

Desarrolladores

Aplicaciones

API

Autoalojamiento

Contribuir

Biblioteca de IU

Resumen

”Uso”

Anatomía

Errores externos

Controles agrupados

Integración nativa y tipos

”Props”

Field.Root

Field.Item

Field.Label

Field.Control

Field.Description

Field.Error

Field.Validity

​Resumen

​”Uso”

​Anatomía

​Errores externos

​Controles agrupados

​Integración nativa y tipos

​”Props”

​Field.Root

​Field.Item

​Field.Label

​Field.Control

​Field.Description

​Field.Error

​Field.Validity

Resumen

”Uso”

Anatomía

Errores externos

Controles agrupados

Integración nativa y tipos

”Props”

Field.Root

Field.Item

Field.Label

Field.Control

Field.Description

Field.Error

Field.Validity