Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 45 additions & 1 deletion website/src/content/pages/components/field.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,9 @@ description: Provides a flexible container for form inputs, labels, and helper t

```tsx
<Field.Root>
<Field.Label />
<Field.Label>
<Field.Indicator />
</Field.Label>
<Field.Input />
<Field.Textarea />
<Field.Select />
Expand All @@ -33,6 +35,48 @@ This example shows how to use the `Field` component with a standard input field.

<Example id="input" />

### Disabled

Set `disabled` on the root to disable the control and mark every part with `data-disabled`.

<Example id="disabled" />

### Invalid

Set `invalid` to show the error text and mark the control with `aria-invalid`. The error text stays mounted and hidden
while the field is valid.

<Example id="invalid" />

### Indicator

`Field.Indicator` is shown only when its `type` matches the field state: `required`, `invalid`, `valid` or `validating`.
Use it inside the label to show a required marker.

<Example id="indicator" />

### Validation

The field validates the control natively, using attributes like `required` and `type="email"`. Set `validationMode` to
choose when results show (`onSubmit`, `onBlur` or `onChange`), and pass `match` to `Field.ErrorText` to show it only for
one native failure such as `valueMissing` or `typeMismatch`.

<Example id="validation" />

### Custom Validation

Pass `validate` to run your own rules. Return an error message, a list of messages, or nothing when the value is valid.
It can also return a promise. The messages are available as `errors` on the field context.

<Example id="custom-validation" />

### Server Errors

Pass `errors` to show errors that come from outside the field, such as a server response. The field is invalid while
`errors` is not empty.

<Example id="server-errors" />

### Textarea

This example illustrates how to use the `Field` component with a textarea element.
Expand Down
12 changes: 12 additions & 0 deletions website/src/content/pages/components/fieldset.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,18 @@ components natively support these contexts, you can also use the `Field` compone

<Example id="basic" />

### Disabled

Set `disabled` on the fieldset to disable every field inside it, including fields that do not render a control.

<Example id="disabled" />

### Invalid

Set `invalid` to show the fieldset error text alongside the errors of each field.

<Example id="invalid" />

### Field

This example demonstrates how to use the `Field` component with a standard input field within a `Fieldset`.
Expand Down
23 changes: 23 additions & 0 deletions website/src/content/pages/overview/upgrade-guide.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -259,6 +259,29 @@ the part being a block, a rotating accordion indicator for example, give it an e

In React, refs to these parts are now typed `HTMLSpanElement`.

### Field and Fieldset use the Zag machines

`Field` and `Fieldset` are now built on `@zag-js/field` and `@zag-js/fieldset`. Fields validate
natively and with `validate`, show results by `validationMode`, and accept server `errors`. Most
usage keeps working; these changes need a look:

- `Field.RequiredIndicator` is replaced by `Field.Indicator`, which takes a `type`.
- The `input`, `textarea` and `select` parts are renamed to `control`, and `required-indicator` to
`indicator`. Update selectors from `[data-field-input]` to `[data-field-control]` and from
`[data-field-required-indicator]` to `[data-field-indicator]`.
- Generated ids are now `{id}:label` and `{id}:control`. Update any code that reads them.
- `Field.ErrorText` stays mounted and hidden while the field is valid, so style it with `[hidden]`
rather than relying on it being removed.
- `Field.Root` no longer sets `role="group"`.

```diff
<Field.Label>
Email
- <Field.RequiredIndicator>*</Field.RequiredIndicator>
+ <Field.Indicator type="required">*</Field.Indicator>
</Field.Label>
```

### `TagsInput` is no longer editable by default

Tags no longer open for editing on double-click unless you pass `editable`. The
Expand Down
1 change: 1 addition & 0 deletions website/src/lib/example-registry.ts
Original file line number Diff line number Diff line change
Expand Up @@ -391,6 +391,7 @@ const exampleModules: Record<string, () => Promise<ExampleModule>> = {
'number-flow/root-provider': () => import('@examples/number-flow/examples/root-provider'),
'number-flow/timing': () => import('@examples/number-flow/examples/timing'),
'number-flow/trend': () => import('@examples/number-flow/examples/trend'),
'number-flow/with-timer': () => import('@examples/number-flow/examples/with-timer'),
'number-input/basic': () => import('@examples/number-input/examples/basic'),
'number-input/context': () => import('@examples/number-input/examples/context'),
'number-input/formatting': () => import('@examples/number-input/examples/formatting'),
Expand Down
Loading