Adv UI

Field

A label, a control, help text and an error message, wired together for screen readers. Validation stays with your app or form library.
Stable
Web
iOS
Android
@advui/core
Source

Basic

Installation

pnpm
pnpm add @advui/core
npm
npm install @advui/core

Usage

import { Field, Input } from '@advui/core'

<Field label="Email" description="We never share it." error={errors.email?.message} required>
  <Input value={email} onChangeText={setEmail} />
</Field>

Examples

With help text

3–20 letters or numbers. Others see it on your profile.

Required and optional

Error message

Type a valid email or a longer password: the app sets `error`, Field shows it.
Enter an email like you@example.org.
At least 8 characters.Too short.

Disabled

You can add notes once the order ships.

Horizontal

Shown on your profile.

Control in a layout

The Input gets the label and help text; the Button is left alone.
Paste the code from your email, or send a new one.

Elements as label, help and error

Starts with sk_. Keep it secret.This key was revoked. Create a new one in Settings.

In a Form

We never share your email.
Password is too short.

API reference

Field

A View that takes every view prop (`padding`, `width`, `backgroundColor`, `theme`, media props, `testID`…). It tells the control inside it, at any depth, its id, state and descriptions through context, and never clones its children. Every core form control reads it: Input, Textarea, Select, Checkbox, Checkbox Group, Switch, Radio Group, Password, Number and OTP Input, the date and time pickers, Combobox, Autocomplete, Multi Select, File Upload, Rich Text Editor and Markdown Editor.
PropTypeDefaultDescription
children requiredReactNode—The control, or a layout with one control in it (an Input next to a Button).
labelReactNode—Visible label, linked to the control. Without one, give the control an `aria-label`.
descriptionReactNode—Help text under the control. Stays visible when there is an error.
errorReactNode—Error message under the help text. It marks the control invalid; `undefined`, `null`, `false` and `""` mean no error.
requiredbooleanfalseRequired marker on the label and `aria-required` on the control.
optionalbooleanfalseAdds "(optional)" to the label. `required` wins when both are set.
optionalTextstring'(optional)'The text `optional` adds, e.g. for another language.
requiredTextstring'required'Read after the label on iOS and Android when `required` is set ("Email, required"): they have no required state.
disabledbooleanfalseDims the label and disables the control. Also on while the surrounding Form is `disabled`.
orientation'vertical' | 'horizontal''vertical'`horizontal` puts the label beside the control, in a third of the width, with the help and error text under the control.
gapSpaceTokens | number'2'Space between the label, control and messages.
fullWidthbooleanfalseFills the container's width, e.g. in a horizontal Form.
idstring—The control's id, which the label targets. Defaults to the `id` of a single child, or a generated one.

useFieldControl

For your own controls: `const props = useFieldControl(ownProps)` fills in what the surrounding Field decides, so a Field wires your control like a core one. Outside a Field it returns the props unchanged, except `disabled`, which is `true` inside a disabled Form.
PropTypeDefaultDescription
idstring—The id the label targets. The control’s own `id` wins.
invalidboolean—`true` when the field has an error, or the control is `invalid` itself.
disabledboolean—`true` when the field, the surrounding Form or the control is disabled. A disabled Form disables the control even without a Field.
aria-requiredboolean—`true` when the field is `required`.
aria-describedbystring—Web: the ids of the error and help text, after the control’s own.
aria-labelstring—Native: the text of the label. The control’s own wins.
accessibilityHintstring—Native: the text of the error and help text.

Accessibility

  • The label targets the control (htmlFor ↔ id), so clicking it focuses the control. A Radio Group or Checkbox Group is named with aria-labelledby instead.
  • Help and error text are linked with aria-describedby on web (error first). On native, the text of the label names the control, the help and error text become its hint, and the visible label is hidden from screen readers so it is not read twice.
  • An error sets aria-invalid on the control; the message is text, not just a red border.
  • required sets aria-required on the control, so screen readers say "required"; the asterisk itself is hidden from them. iOS and Android have no required state, so there the control’s name ends in requiredText ("Email, required"). "(optional)" is part of the label.
  • A disabled field disables its control, so it leaves the Tab order and is announced as dimmed.

Responsive behavior

orientation is a plain prop, not a style, so the markup never depends on the screen size. Use vertical (the default) on narrow screens.

Platform notes

iOS
The text of the label names the control, and the help and error text become the VoiceOver hint. iOS has no required or invalid state for screen readers, so put it in the error text.
Android
The text of the label names the control, and the help and error text become the TalkBack hint. Android has no required or invalid state for screen readers, so put it in the error text.

Related components

Form
Input
Label
Select
Checkbox
Password Input
Since v0.4.0Last updated Nov 2, 2026Edit this page on GitHub
PreviousDate Time Picker
NextForm