TextField

A text field is a native <input> or <textarea> with a label, a description and an error message. It has Field built in for the labelling, and adds the value, read-only mode, form reset, and hover and focus state on every part. The browser keeps doing the editing: typing, selection, input methods, autofill, undo, Enter submitting the form from an <input> and adding a line in a <textarea>.

A native text control needs no WAI-ARIA pattern. Labelling follows the APG practice on names and descriptions.

<!doctype html><meta charset="utf-8"><style>/* The page's layout. The text fields' look is @uniaria/styles' default. */
:root {
  font:
    15px/1.5 system-ui,
    sans-serif;
}
body {
  display: grid;
  gap: 1rem;
  margin: 1.5rem;
  background: var(--uni-surface-color);
  color: var(--uni-text-color);
}
.form {
  display: grid;
  gap: 1rem;
  max-inline-size: 20rem;
}
</style><form class="form" novalidate>
  <uni-text-field id="username" required>
    <div data-uni="text-field">
      <label data-element="Label">Username</label>
      <div data-element="Wrapper">
        <span aria-hidden="true">@</span>
        <input data-element="Input" name="username" autocomplete="username" />
      </div>
      <p data-element="Description">Letters, digits and underscores.</p>
      <p data-element="Error" hidden>
        Use only letters, digits and underscores.
      </p>
    </div>
  </uni-text-field>

  <uni-text-field id="bio">
    <div data-uni="text-field">
      <label data-element="Label">Bio</label>
      <div data-element="Wrapper">
        <textarea
          data-element="Input"
          name="bio"
          rows="3"
          maxlength="160"
        ></textarea>
      </div>
      <p data-element="Description">0 of 160 characters</p>
    </div>
  </uni-text-field>
</form>
<output id="log">Type a username with a space, then leave the field.</output>
<script src="/demo/text-field.js"></script><script>const username = document.getElementById('username');
const bio = document.getElementById('bio');
const count = bio.querySelector('[data-element="Description"]');
const log = document.getElementById('log');
const isValid = (value) => /^\w*$/.test(value);

// Check on blur, as many forms do; once invalid, check on every change.
username.addEventListener('focuschange', (event) => {
  log.textContent = `focuschange: ${event.detail}`;
  if (!event.detail) {
    username.toggleAttribute(
      'invalid',
      !isValid(username.instance.getState().value),
    );
  }
});
username.addEventListener('valuechange', (event) => {
  log.textContent = `valuechange: "${event.detail}"`;
  if (username.hasAttribute('invalid') && isValid(event.detail)) {
    username.removeAttribute('invalid');
  }
});

bio.addEventListener('valuechange', (event) => {
  count.textContent = `${event.detail.length} of 160 characters`;
});
</script>

import { textField } from '@uniaria/core/text-field';
import { useBehavior } from '@uniaria/react';

export function EmailField(props: {
  error?: string;
  onEmailChange(email: string): void;
}) {
  const email = useBehavior(textField, {
    isRequired: true,
    isInvalid: props.error !== undefined,
    onValueChange: props.onEmailChange,
  });
  return (
    <div {...email.parts.root}>
      <label {...email.parts.label}>Email</label>
      <div {...email.parts.wrapper}>
        <input {...email.parts.input} name="email" type="email" />
      </div>
      <p {...email.parts.description}>We never share it</p>
      <p {...email.parts.error}>{props.error}</p>
    </div>
  );
}

<script setup lang="ts">
import { textField } from '@uniaria/core/text-field';
import { useBehavior } from '@uniaria/vue';

const props = defineProps<{ error?: string }>();
const emit = defineEmits<{ emailChange: [email: string] }>();

const email = useBehavior(textField, () => ({
  isRequired: true,
  isInvalid: props.error !== undefined,
  onValueChange: (value) => emit('emailChange', value),
}));
</script>

<template>
  <div v-bind="email.parts.root">
    <label v-bind="email.parts.label">Email</label>
    <div v-bind="email.parts.wrapper">
      <input v-bind="email.parts.input" name="email" type="email" />
    </div>
    <p v-bind="email.parts.description">We never share it</p>
    <p v-bind="email.parts.error">{{ error }}</p>
  </div>
</template>

<uni-text-field id="email" required>
  <div data-uni="text-field">
    <label data-element="Label">Email</label>
    <div data-element="Wrapper">
      <input data-element="Input" name="email" type="email" />
    </div>
    <p data-element="Description">We never share it</p>
    <p data-element="Error" hidden>Enter a valid email</p>
  </div>
</uni-text-field>

<script type="module">
  import '@uniaria/elements/text-field';

  document.querySelector('#email').addEventListener('valuechange', (event) => {
    console.log(event.detail);
  });
</script>

Without value, the field is uncontrolled: it keeps the typed text and reports each change. defaultValue (the default-value attribute) sets the text it starts with.

Render a <textarea> as the input part. Nothing else changes: there is no separate TextArea component, and Enter adds a line instead of submitting.

<uni-text-field>
  <label data-element="Label">Bio</label>
  <textarea data-element="Input" name="bio" rows="3" maxlength="160"></textarea>
</uni-text-field>

Native attributes such as maxlength, pattern or rows are yours and keep their native effects. Growing a textarea with its content isn’t built in.

The wrapper part is the box around the input, where icons, units, a prefix or a clear button go. A press anywhere on it outside the input and outside any other control (a link, a button, a label) focuses the input, so the whole box behaves like the input. Hover and focus are written on every part, so the box can show the hover and focus styles.

<uni-text-field>
  <label data-element="Label">Website</label>
  <div data-element="Wrapper">
    <span aria-hidden="true">https://</span>
    <input data-element="Input" name="website" />
  </div>
</uni-text-field>

Pass value and update it from onValueChange. You can change what the user typed, for example to upper case:

const [code, setCode] = useState('');
const coupon = useBehavior(textField, {
  value: code,
  onValueChange: (next) => setCode(next.toUpperCase()),
});

<script setup lang="ts">
const code = ref('');
const coupon = useBehavior(textField, () => ({
  value: code.value,
  onValueChange: (next) => (code.value = next.toUpperCase()),
}));
</script>

<template>
  <div v-bind="coupon.parts.root">
    <label v-bind="coupon.parts.label">Coupon</label>
    <input v-bind="coupon.parts.input" name="coupon" />
  </div>
</template>

<script type="module">
  const coupon = document.querySelector('#coupon');
  coupon.value = ''; // setting the property makes it controlled
  coupon.addEventListener('valuechange', (event) => {
    coupon.value = event.detail.toUpperCase();
  });
</script>

A controlled field keeps the typed text on screen while you answer, so a store that updates late loses no keystrokes and the caret stays put:

• A new value that echoes what the field reported leaves the input alone.
• Any other value, such as a transformed one or one set from elsewhere, replaces the text at once, and the caret moves to the end.
• Text you never accept goes back to your value when the input loses focus.
• While an input method is composing text, a new value waits until the composition ends.

Put name on the input: the native input is what the form submits. On the form’s reset, the field goes back to its default, as a native input goes back to its value attribute. An uncontrolled field follows defaultValue again (empty without one), even one you set after it rendered, and reports the change through valueChange. A controlled field reports defaultValue, or without one the value it started with, and keeps your value until you accept. A reset cancelled with preventDefault() before it reaches the form changes nothing.

In a Form, the form holds the value under the field’s name, checks it when focus leaves the input (isRequired, the constraints you write on the input, such as type="email" or minlength, and validate) and shows the first error in the errorText part. Without a form, set isInvalid from your own checks, for example when focusChange reports false, as the demo does. See Forms.

A part keeps an id you give it, and everything that refers to the part follows it; UniAria writes an id only on a part that has none (see Ids).

Every part but the input is optional. The parts link as Field’s do. Set disabled and readonly through the props, not on the input: UniAria writes those attributes and removes yours.

In a Form, TextField also takes name, form, validate, validationTrigger, validationDelay, validationMessages, dependsOn, isEqual and shouldPreserve: see Field props for the form.

The custom element dispatches each event on itself, bubbling, with the value in detail. In React, the input’s onFocus, onBlur, onInput, onPointerEnter, onPointerLeave, onCompositionStart and onCompositionEnd come from UniAria, and passing your own replaces them: use the events above instead. onChange, onKeyDown and the rest are yours. In Vue, a listener of your own runs beside UniAria’s.

Typing, hovering and focusing never render your component again. To render something from state in React or Vue, select it (Vue gives a ref):

const isFocused = useBehaviorState(email, (state) => state.isFocused);

On the custom element, read element.instance.getState(). See State.

Every state attribute goes on every part, so the box, the label and the messages can follow the input: draw the focus ring on the wrapper with [data-focused], color the label with [data-invalid]. The error part also gets hidden while it isn’t shown. TextField sets no inline styles.

The optional @uniaria/styles package styles every part, as in the demo above, whose CSS tab holds only the page’s layout. The wrapper is the box, with the focus ring on any focus inside it and the danger border while invalid; the input is bare inside it, beside your own prefix or suffix. Without a wrapper the input has no box: use Field around a native input for that.

TextField handles no keys; the input keeps its native editing.

• Spoken output. A field labelled “Email” reads “textbox, Email” when empty, “textbox, Email, jane@example.com” with a value, “textbox, Email, jane@example.com, read only” while read-only and “textbox, Email, disabled” while disabled. A <textarea> is a textbox too; type="search" reads “searchbox”. The description, the error and the required and invalid states follow, as in Field.
• Labels. A placeholder isn’t a label: always render the label part, or pass labelledBy.
• Errors. Setting isInvalid shows the error and announces it, as Field does. Don’t add role="alert" to the error part.
• Read-only or disabled. A read-only input stays in the Tab order and is read with its value. A disabled one leaves it, so prefer read-only for a value the user should still be able to find and copy.
• Tooltips. A Tooltip linked through tooltip describes the input, and typing closes it.

• Controlled typing is buffered. React and React Aria put a refused value back right after the keystroke. TextField keeps the typed text until the input loses focus, so an echo that arrives late doesn’t move the caret or drop keystrokes. A transformed value still replaces the text at once.
• One component for both elements. As in React Aria, a <textarea> is a TextField; there is no elementType to set.
• The box focuses the input. A press on the wrapper outside any control focuses the input. React Aria has no such part.
• Validation is the form’s. In a Form, validate and the native constraints you write on the input are checked, as React Aria’s validate and native validation do; outside one, pass isInvalid.
• Form reset goes back to the defaultValue the field has when the form resets, as a native input does; React Aria keeps the one it started with. A controlled field without defaultValue goes back to the value it started with, as in React Aria.