# Field

Raiz do campo de formulário. Liga rótulo, ajuda e erro por acessibilidade.

Compõe com `FieldLabel`, `Input`, `FieldDescription` e `FieldError`. A ligacao e
automática: não escreva `htmlFor` nem `aria-describedby` a mao.

Marque inválido com `invalid` na raiz e mostre a mensagem com
`<FieldError match>`. `disabled` na raiz desabilita o conjunto.

## No React Native

Traduz: o `@rivocode/ui-native` exporta `Field` - `label`, `description` e `error` como props; o erro vence a descrição, como no web, e o texto que chega depois entra por fade. A API não é a mesma do web (no nativo tudo é controlado), e a [tabela de paridade](/react-native) diz o que muda peça a peça.

## Importação

```tsx
import { Field } from '@rivocode/ui'
```

## Exemplos

### Básico

```tsx
import { Field, FieldDescription, FieldError, FieldLabel, Input } from '@rivocode/ui'

export function Basic() {
  return (
    <div className="flex max-w-sm flex-col gap-4">
      <Field name="empresa">
        <FieldLabel>Empresa</FieldLabel>
        <Input placeholder="RivoCode Tecnologia" />
        <FieldDescription>Razão social como consta no CNPJ</FieldDescription>
      </Field>
    </div>
  )
}
```

### Com erro

```tsx
import { Field, FieldDescription, FieldError, FieldLabel, Input } from '@rivocode/ui'

export function WithError() {
  return (
    <div className="max-w-sm">
      <Field name="email" invalid>
        <FieldLabel>Email</FieldLabel>
        <Input placeholder="você@empresa.com" />
        <FieldError match>Informe um email válido</FieldError>
      </Field>
    </div>
  )
}
```

### Tamanhos

```tsx
import { Field, FieldDescription, FieldError, FieldLabel, Input } from '@rivocode/ui'

export function Sizes() {
  return (
    <div className="flex max-w-sm flex-col gap-4">
      <Field name="a">
        <FieldLabel>Pequeno</FieldLabel>
        <Input size="sm" placeholder="Denso, para tabela" />
      </Field>
      <Field name="b">
        <FieldLabel>Médio</FieldLabel>
        <Input size="md" placeholder="O padrão" />
      </Field>
      <Field name="c">
        <FieldLabel>Grande</FieldLabel>
        <Input size="lg" placeholder="Para formulário curto e destacado" />
      </Field>
    </div>
  )
}
```

### Desabilitado

```tsx
import { Field, FieldDescription, FieldError, FieldLabel, Input } from '@rivocode/ui'

export function Disabled() {
  return (
    <div className="max-w-sm">
      <Field name="cnpj" disabled>
        <FieldLabel>CNPJ</FieldLabel>
        <Input defaultValue="60.139.541/0001-27" />
        <FieldDescription>Não pode ser alterado depois do cadastro</FieldDescription>
      </Field>
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `actionsRef` | `RefObject<FieldRootActions \| null>` |  | 0.4.0 | A ref to imperative actions. |
| `dirty` | `boolean` |  | 0.4.0 | Whether the field's value has been changed from its initial value. |
| `disabled` | `boolean` |  | 0.4.0 | Whether the component should ignore user interaction. |
| `invalid` | `boolean` |  | 0.4.0 | Whether the field is invalid. |
| `name` | `string` |  | 0.4.0 | Identifies the field when a form is submitted. |
| `render` | `ComponentRenderFn<HTMLProps, FieldRootState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | 0.4.0 | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |
| `touched` | `boolean` |  | 0.4.0 | Whether the field has been touched. |
| `validate` | `((value: unknown, formValues: Record<string, any>) => string \| string[] \| Promise<string \| string[] \| null> \| null)` |  | 0.4.0 | A function for custom validation. |
| `validationDebounceTime` | `number` |  | 0.4.0 | How long to wait between `validate` callbacks if `validationMode="onChange"` is used. |
| `validationMode` | `FormValidationMode` |  | 0.4.0 | Determines when the field should be validated. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Partes

O componente se monta com as peças abaixo. Todas vêm de `@rivocode/ui`.

### FieldDescription

A ajuda abaixo do campo: formato esperado, para que serve, o que vai acontecer.

Entra no `aria-describedby` do controle, então é lida junto com o campo em vez
de ficar invisível para quem usa leitor de tela.

| Prop | Tipo | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `render` | `ComponentRenderFn<HTMLProps, FieldDescriptionState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | 0.4.0 | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

### FieldError

A mensagem de erro do campo.

Só aparece quando o campo está inválido, e marca `aria-invalid` no controle
junto. Vermelho sozinho não diz nada a quem não distingue a cor, a frase é
que diz.

| Prop | Tipo | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `match` | `boolean \| keyof ValidityState` |  | 0.4.0 | Determines whether to show the error message according to the field's [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState). |
| `render` | `ComponentRenderFn<HTMLProps, FieldErrorState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | 0.4.0 | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

### FieldLabel

O rótulo do campo.

Dentro de um `Field`, a Base UI liga rótulo e controle sozinha, sem `htmlFor`
escrito à mão e sem `id` inventado. Clicar no rótulo foca o campo.

| Prop | Tipo | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `nativeLabel` | `boolean` |  | 0.4.0 | Whether the component renders a native `<label>` element when replacing it via the `render` prop. |
| `render` | `ComponentRenderFn<HTMLProps, FieldLabelState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | 0.4.0 | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

## Ver também

- [Autocomplete](/componentes/autocomplete.md)
- [Calendar](/componentes/calendar.md)
- [Checkbox](/componentes/checkbox.md)
- [CheckboxGroup](/componentes/checkbox-group.md)
- [ColorPicker](/componentes/color-picker.md)
- [Combobox](/componentes/combobox.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)