Label

Label renders a form field's label, optional required asterisk, and optional instructions text. Every text-like field in this library uses it internally to keep that presentation consistent, but it's also a standalone element you can use directly.

Overview

API

Examples

Accessibility

When to use

Reach for a label directly only when you're building a custom form field of your own, one that isn't already one of this library's own field components, and you still want the same label, asterisk, and instructions presentation they share. Every built-in field already renders one internally from its own label and instructions options, so you'll rarely need it on its own.

Install & usage

npm install @eunomia/elements

import "@eunomia/elements/label.js";

<eun-label
  label="Email address"
  for="field"
  instructions="Used to sign in"
></eun-label>

Importing the file registers <eun-label> as a custom element. It renders its own text only, and doesn't focus, own, or validate a field by itself. for just tells it which element to focus when its wrapper is clicked.

Guidance

Always set for to the id of the field it labels, inside the same shadow root
Keep label text short and specific ("Email address", not "Enter your info here")
Use instructions for format guidance ("Include your country code"), not error messages

Using eun-label as a substitute for a real field's accessible name: see the Accessibility tab
Duplicating the field's placeholder text into instructions

Properties

Attributes

Name	Type	Default	Description
label	string	—	The text of the label. If a label is given through a slot, this property acts as a fallback
for	string	—	The id of the form field the label is associated with. Used to focus the target element when clicking on the label
required	boolean	false	Whether the field is required. When true, an asterisk is displayed next to the label
instructions	string	—	Optional instructions or helper text, displayed below the label when provided

Import the exact TypeScript type behind any property above, see Types.

Slots

Name	Description
label	Custom label content, falling back to the label property
instructions	Custom instructions content, falling back to the instructions property

Basic label

<eun-label label="Email address" for="field"></eun-label>

<eun-label label="Email address" for="field" />

Required

<eun-label label="Email address" for="field" required></eun-label>

<eun-label label="Email address" for="field" required />

With instructions

<eun-label
  label="Password"
  for="field"
  instructions="At least 8 characters"
></eun-label>

<eun-label label="Password" for="field" instructions="At least 8 characters" />

Slotted label content

The label slot overrides the label property entirely, useful when the label needs inline markup (e.g. a tooltip trigger) rather than plain text.

<eun-label for="field">
  <span slot="label">Email address</span>
</eun-label>

Keyboard interactions

eun-label itself holds no keyboard focus and isn't part of the tab order. Keyboard users reach the field it labels directly via Tab, the same as any other native <label>/field pair. Clicking the label's wrapper is a pointer-only convenience that mirrors that behavior for mouse/touch users.

Not a substitute for an accessible name

eun-label renders its text inside its own shadow root, a different shadow tree than the field it labels (e.g. eun-input's internal <input>). Native for/id association and aria-labelledby both rely on ID references, and ID references don't cross shadow-root boundaries in current browsers, so nothing here programmatically ties the visible label text to the field's accessible name. The consuming field component is responsible for its own accessible name (typically via aria-label, computed from the same string passed into eun-label's label property), not eun-label itself. See eun-input's Accessibility tab for the concrete pattern.

Required asterisk

The * shown when required is set is purely visual (aria-hidden isn't set explicitly, but it carries no semantic meaning on its own): the field itself must expose required/aria-required for assistive technology to announce that the field is mandatory. Don't rely on the asterisk alone to convey that.

Instructions vs. errors

instructions is meant for static format guidance, always present regardless of validity. It is not a substitute for a field's error message, which should be associated with the field via aria-describedby and only shown while actually invalid.