Holo Form Field

The <holo-form-field> component wraps a <label>, a slotted control, an optional hint, and an error message region. It automatically generates and forwards id/aria-describedby/aria-invalid/aria-required attributes onto the first slotted element, so native controls and form-associated custom elements are labelled and described without manual wiring.

When to use

Use it for:

Giving any single control a visible label, optional hint and error message with consistent layout.
Wrapping native controls (<input>, <select>) or custom ones that do not have their own label.

Don’t use it for:

Wrapping Text Field, Textarea, Select or Checkbox when you already set their own label. They render their own label and error.
Grouping several related controls. Use a <fieldset> with a <legend>.
Page-level error summaries. Use Alert.

Live Previews

Default with hint

<holo-form-field label="Email address" hint="We'll never share your email.">
  <input type="text" placeholder="you@example.com" />
</holo-form-field>

Required

<holo-form-field label="Full name" required>
  <input type="text" />
</holo-form-field>

Invalid

<holo-form-field label="Email address" invalid error-message="Please enter a valid email address.">
  <input type="text" value="not-an-email" />
</holo-form-field>

Accessibility

The component creates a native <label>, the hint and the error message as light-DOM children of <holo-form-field> (marked data-holo-form-field) and projects them into named slots. They sit in the same tree as your control, so the label’s for and the control’s aria-describedby resolve: the control’s accessible name is the label, and its description is the hint followed by the error. The error has role="alert" and is only present when invalid is set and errorMessage is provided.

On the first slotted element the component sets a generated id (if it has none), aria-describedby (hint, and error when shown), aria-invalid="true" when invalid, and aria-required="true" when required. The required marker is aria-hidden, so it is not part of the name.

The component is not interactive and has no keyboard behaviour. Keyboard use is that of the slotted control.

The created elements are ordinary light-DOM elements, so page-wide styles for label can reach them. Do not remove or reorder them from your framework code.
The for association works for labelable elements: native <input>, <select>, <textarea>, and form-associated custom elements. A custom element that renders its own input in a shadow root (such as Text Field) is not named by this label; use that component’s own label instead.

You provide:

A label. It is required.
The control itself. Set required and invalid on the wrapper; the wrapper copies the ARIA state onto the control, but a native required attribute (and validation) is still yours to set.
Error text that says what is wrong and how to fix it, not colour alone.

API Reference

Importing

import '@philbob-sideprojects/hololink-ui/holo-form-field';

Properties

Property	Attribute	Type	Default	Description
`errorMessage`	`error-message`	`string`	—	Error message rendered (and announced) when `invalid` is true.
`hint`	`hint`	`string`	—	Optional hint/help text rendered below the control.
`invalid`	`invalid`	`boolean`	`false`	Marks the field as invalid — shows the error message and sets `aria-invalid`/`aria-describedby` on the slotted control.
`label` (required)	`label`	`string`	—	The visible label text describing the wrapped control.
`required`	`required`	`boolean`	`false`	Marks the field as required, appending a visual indicator to the label and setting `aria-required` on the slotted control.

Slots

Slot	Description
(default)	The form control (input, textarea, or custom element) to label and describe.
`error`
`hint`
`label`

CSS custom properties

Property	Description
`--holo-form-field-error-color`	Text color of the error message.
`--holo-form-field-error-gap`	Space above the error message.
`--holo-form-field-hint-color`	Text color of the hint.
`--holo-form-field-hint-gap`	Space between the control and the hint.
`--holo-form-field-label-color`	Text color of the label.
`--holo-form-field-label-gap`	Space between the label and the control.
`--holo-form-field-required-color`	Color of the required indicator.