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.
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> );}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.'];}<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>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> `; }}<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>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.
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. |
idPrefix
attribute id-prefix | string | – | Goes in front of every DOM id the element renders, so two elements with the same uid in different forms render different ids. GolemUI Forms sets it to the form's formName. Only ids and the references to them (for, aria-describedby…) take it: data-cy attributes and event details keep the bare uid. |
domId read-only, no attribute | string | – | The id of the element's control: uid, behind idPrefix when it is set. |
Styling
Section titled “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.