Label

<gui-label> is the label of a GolemUI Components field as an element of its own: the label text, the required marker and the hint, styled like every other field’s. Use it to label a control you build yourself, so it looks and reads like the fields around it. The fields render their own label, so you rarely need it next to them.

Code of the example above

React

PartsCustomField.tsx

import { useState } from 'react';
import { GuiErrors, GuiLabel } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';

const errors = ['Pick a darker color for enough contrast.'];

export function PartsCustomField() {
  const [input, setInput] = useState<HTMLInputElement | null>(null);

  return (
    <div className="gui-field">
      {/* The label sets the input's ARIA attributes: describedby, invalid, required. */}
      <GuiLabel
        uid="brand-color"
        label="Brand color"
        hint="Used for buttons and links."
        required
        targetElement={input ?? undefined}
        errors={errors}
      />
      <div className="gui-widget">
        <input
          ref={setInput}
          id="brand-color"
          type="color"
          defaultValue="#b5531f"
        />
      </div>
      <GuiErrors uid="brand-color" errors={errors} />
    </div>
  );
}

Angular

parts-custom-field.component.ts

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@golemui/gui-components/errors';
import '@golemui/gui-components/label';

@Component({
  selector: 'app-parts-custom-field',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <div class="gui-field">
      <!-- The label sets the input's ARIA attributes: describedby, invalid, required. -->
      <gui-label
        uid="brand-color"
        label="Brand color"
        hint="Used for buttons and links."
        required
        [targetElement]="input"
        [errors]="errors"
      ></gui-label>
      <div class="gui-widget">
        <input #input id="brand-color" type="color" value="#b5531f" />
      </div>
      <gui-errors uid="brand-color" [errors]="errors"></gui-errors>
    </div>
  `,
})
export class PartsCustomFieldComponent {
  errors = ['Pick a darker color for enough contrast.'];
}

Vue

PartsCustomField.vue

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import '@golemui/gui-components/errors';
import '@golemui/gui-components/label';
import '@golemui/gui-components/index.css';

const input = useTemplateRef<HTMLInputElement>('input');
const errors = ['Pick a darker color for enough contrast.'];
</script>

<template>
  <div class="gui-field">
    <!-- The label sets the input's ARIA attributes: describedby, invalid, required. -->
    <gui-label
      uid="brand-color"
      label="Brand color"
      hint="Used for buttons and links."
      :required="true"
      :targetElement="input ?? undefined"
      :errors.prop="errors"
    ></gui-label>
    <div class="gui-widget">
      <input id="brand-color" ref="input" type="color" value="#b5531f" />
    </div>
    <gui-errors uid="brand-color" :errors.prop="errors"></gui-errors>
  </div>
</template>

Lit

parts-custom-field.ts

import { LitElement, html } from 'lit';
import { customElement, query } from 'lit/decorators.js';
import type { GuiLabel } from '@golemui/gui-components';
import '@golemui/gui-components/errors';
import '@golemui/gui-components/label';
import '@golemui/gui-components/index.css';

const errors = ['Pick a darker color for enough contrast.'];

@customElement('parts-custom-field')
export class PartsCustomField extends LitElement {
  @query('gui-label[uid="brand-color"]') private label!: GuiLabel;
  @query('#brand-color') private input!: HTMLInputElement;

  protected override createRenderRoot() {
    return this;
  }

  protected override firstUpdated() {
    // The label sets the input's ARIA attributes: describedby, invalid,
    // required.
    this.label.targetElement = this.input;
  }

  override render() {
    return html`
      <div class="gui-field">
        <gui-label
          uid="brand-color"
          label="Brand color"
          hint="Used for buttons and links."
          required
          .errors=${errors}
        ></gui-label>
        <div class="gui-widget">
          <input id="brand-color" type="color" value="#b5531f" />
        </div>
        <gui-errors uid="brand-color" .errors=${errors}></gui-errors>
      </div>
    `;
  }
}

Vanilla JS

index.html

<div class="gui-field">
  <gui-label uid="brand-color" label="Brand color" hint="Used for buttons and links." required></gui-label>
  <div class="gui-widget">
    <input id="brand-color" type="color" value="#b5531f" />
  </div>
  <gui-errors uid="brand-color" errors='["Pick a darker color for enough contrast."]'></gui-errors>
</div>

<script type="module">
  // The label sets the input's ARIA attributes: describedby, invalid, required.
  const label = document.querySelector('gui-label[uid="brand-color"]');
  label.targetElement = document.querySelector('#brand-color');
  label.errors = ['Pick a darker color for enough contrast.'];
</script>

Usage

import '@golemui/gui-components/label';

Give it the same uid as your control’s id. It renders a native <label for> with that id, so clicking the label focuses the control. Set native to false for a control that a <label> can’t name, such as a custom widget built from divs.

Point targetElement at your control, or a list of controls, from JavaScript. The label then keeps the control’s ARIA attributes in sync with its own state: aria-describedby for the hint, aria-required, aria-readonly, aria-disabled, and aria-invalid with aria-errormessage while errors hold messages. Pair it with a gui-errors of the same uid to show those messages.

API

Properties

Property	Type	Default	Description
targetElement property only	HTMLElement[] | HTMLElement	–	The control or controls the label describes; they receive its ARIA attributes.
label	string	–	Text of the label.
hint	string	–	Help text shown under the label.
required	boolean	–	Adds the required marker, and aria-required to the target.
errors	string[]	[]	Errors of the labelled control, which set aria-invalid on it.
disabled	boolean	false	Sets aria-disabled on the target.
readOnly attribute readonly	boolean	false	Sets aria-readonly on the target.
touched	boolean	–	Whether the labelled control was touched: errors wait for it unless unset.
native	boolean	true	Renders a native <label for>. Turn it off for targets that a <label> cannot name.
uid	string	–	The id of the element's control. The ids of its label, hint and errors derive from it. Optional: when it is not set, the element generates one from its tag name and a page-wide counter, e.g. gui-textinput-3. Generated ids depend on creation order, so a server-rendered element must set uid or its ids will not match after hydration.

Styling

<gui-label> renders the parts every field’s label has:

Class	Part
gui-label	The label, with the text and the hint.
gui-label__text	The label text and the required marker.
gui-widget-hint	The hint.

It reads the same tokens as the text input’s label: see Overriding styles.