Todos los componentes (204)

Formulario

Campos · Form

Qué es y cuándo usarlo

Form valida un formulario entero con un solo esquema (schema), el mismo que usa el servidor, y coloca cada error donde toca. Se envía con SubmitButton.

Cuándo usarlo

Una pantalla con varios campos que se envían juntos: un alta, un pago, un contacto.
Cuando ya tienes el esquema de validación del servidor: se reutiliza tal cual, sin repetir las reglas.

Cuándo no

Un campo suelto que guarda al salir del foco: usa el campo directamente con su onChange.
Un buscador o un filtro: eso no es un formulario que se envía.

Lo que hace sin pedirlo: resumen de errores arriba con role="alert", el error de cada campo bajo su campo, el foco al primero que falla, SubmitButton en carga mientras envía (así no se envía dos veces), y lo que devuelva onSubmit (errors por campo o error general) colocado en su sitio. Por defecto valida al enviar; validateOn lo cambia a onBlur o onChange, y summary={false} quita el resumen.

No depende de ninguna librería de validación: va por Standard Schema, así que vale cualquier esquema que lo cumpla. La biblioteca no importa ninguna.

Y el cinturón: la validación del navegador es comodidad, no seguridad. El mismo esquema tiene que correr en el servidor — con un curl se salta el formulario entero.

Teclado: Tab recorre los campos en el orden del documento; Intro envía desde cualquier campo de una línea. Al enviar con errores, el foco salta al primero que falla.

Accesibilidad: cada error se asocia a su campo con aria-describedby y el campo se marca inválido. El resumen se anuncia al enviar, no antes.

Campos conectados: texto (FormTextField, FormTextArea, FormPasswordField, FormPhoneField, FormDocumentField, FormIbanField, FormCodeField), numéricos (FormNumberField, FormQuantityPicker, FormSlider, FormRating), de elegir (FormSelect, FormMultiSelect, FormSearchField, FormRadioGroup, FormSegmentedGroup, FormCheckbox, FormSwitch, FormCascader, FormTreeSelect), de fecha, hora y color (FormDatePicker, FormDateRangePicker, FormTimeField, FormColorPicker) y de valor compuesto (FormCardField, FormAddressField, FormSignatureField, FormFileUpload). Todos toman name y sacan su valor y su error del formulario. Para cualquier otro campo, FormField recibe una función que pinta lo que quieras con value, onChange, onBlur y error.

Aspecto fino: cada campo mantiene sus variables CSS --amset-field-*.

Cómo se ve

Envía vacío para ver los errores.

<Form schema={esquemaAlta} initialValues={{ nombre: '', email: '', acepta: false }} onSubmit={guardar}>
  <FormTextField name="nombre" label="Nombre y apellidos" required />
  <FormTextField name="email" label="Correo" type="email" required />
  <FormCheckbox name="acepta">Acepto las condiciones</FormCheckbox>
  <SubmitButton>Dar de alta</SubmitButton>
</Form>

Props

Se importa con import { Form } from '@amset/ui/form'. Las obligatorias van marcadas.

Prop	Tipo	Para qué sirve
`schema`obligatoria	`StandardSchema`	Esquema Standard Schema (Zod 4, Valibot...). El mismo que valida el servidor.
`initialValues`	`DefaultValues<TValues>`	—
`onSubmit`obligatoria	`(values: TValues) => void \| SubmitResponse \| Promise<void \| SubmitResponse>`	Se llama solo con los datos ya validados. Si devuelve `errors`, se pintan en sus campos; si devuelve `error`, sale en el resumen de arriba.
`children`obligatoria	`ReactNode`	—
`summary`	`boolean`	Resumen de errores al principio del formulario. Se anuncia al enviar.
`className`	`string`	—
`validateOn`	`'onSubmit' \| 'onBlur' \| 'onChange'`	Cuando se valida: al enviar (por defecto) o al salir de cada campo.

Acepta además los atributos del elemento que pinta: className, style, data-*, aria-* y sus eventos.

En el banco de pruebas

Cada estado y cada variante, para tocarlos de uno en uno, en su ficha de ui.amset.tech: