Field

Field wrapper that combines label, input, and feedback messages into one cohesive unit. It receives a component (Input, Checkbox, InputSelect, etc.) and injects value, onChange, variant, and reset into it — it is the piece that marries an input to the Form (RHF + Zod) and to the validation UI.

When to use

✅ Use when…	🚫 Avoid when…
Whenever an input needs a label and/or feedback message in the design system standard. As a `Form` item: each key in `fields` becomes a `Field`.	In very simple forms where there is only a button and a search field, and the label would be redundant with the placeholder. When you need a custom layout for label/input (e.g. side by side, complex grid) — in those cases use the child components directly and build your own wrapper.

Visual states

Common combinations of label + hint + state:

Name

What should we call you?

EmailOptional

We will use it to send you updates.

Password

Password must be at least 8 characters long.

Confirmation

Passwords match.

Tokenapenas leitura

Automatically generated.

Label, optionalText and hints

Stable hint slot

The hint line always reserves one line of micro text — empty, hidden or filled. A Field that goes from idle to error on submit keeps the same height, so the next input or the submit button does not jump. Do not pad hintText with a blank space, and do not bump the parent Form gap to compensate.

Hint with inline action

hintText accepts a ReactNode, not just a string. Use this for affixes that previously had to be rendered outside the Field — an action ("use all"), a limit Text, a help link:

<Field
  component={Input}
  label="Amount"
  hintText={
    <Flex flexDirection="row" wrap="wrap" justifyContent="between" width="100%">
      <Text text="Daily limit: R$ 5.000" />
      <Button variant="linked" size="extraSmall" text="use all" onClick={fillMax} />
    </Flex>
  }
/>

hintSuccessText and hintErrorText also accept a ReactNode.

`Field` inside `Form`

Inside a Form, the Field must be declared as an object in fields:

<Form
  handleSubmit={console.log}
  fields={{
    email: {
      label: 'Email',
      component: Input,
      validation: z.email('Required'),
      inputProps: { type: 'email', placeholder: 'you@company.com' },
    },
  }}
/>

Messages returned by the field's validation are automatically turned into hintErrorText.

Do not pass value/onChange directly to a Field inside a Form — the Form (via React Hook Form) injects them automatically through inputProps.

Gotchas

Do not set error and success at the same time — use variant instead, which expresses the combined state.
Avoid duplicating the label as placeholder when both are present — placeholder should show an example value, not repeat the label.

Properties


Prop	Type	Default	Description
`component *`	`any`	—	—
`error`	`boolean`	—	—
`errors`	`any`	—	—
`fieldProps`	`DefaultFlexInterface`	—	—
`hideLabel`	`boolean`	—	—
`hintErrorText`	`ReactNode`	`Something went wrong`	Message displayed when `error`. Accepts `ReactNode` (a string when it comes from `Form` validation).
`hintSuccessText`	`ReactNode`	`Everything is alright`	Message displayed when `success`. Accepts `ReactNode`.
`hintText`	`ReactNode`	—	Neutral message below the input. Accepts `ReactNode` (not just `string`): besides text, it can carry inline actions (e.g. a "use all" button) or a supporting `Text` (e.g. a daily limit) — previously these affixes had to be rendered as siblings outside the `Field`. Backward-compatible widening (`string ⊂ ReactNode`).
`inputProps`	`any`	—	—
`label`	`string`	—	—
`name`	`string`	—	—
`optionalText`	`string`	—	—
`readOnly`	`boolean`	—	—
`readOnlyText`	`string`	`apenas leitura`	—
`setFieldValue`	`UseFormSetValue<any>`	—	—
`success`	`boolean`	—	—
`value`	`any`	—	—
`variant`	`"default" \| "success" \| "error"`	—	—

In addition to the props above, every component accepts the layout props (spacing, color, flex/grid, sizing, border) — not repeated here.