GUILD OF GLEKS UIv21.19.0

gog-inputfield

Input Field

A text field with five sizes, leading/trailing icons that can double as buttons, a built-in password reveal toggle, and full ControlValueAccessor support.

Overview

Import the component and drop it into a template.

typescript
import { InputfieldComponent } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [InputfieldComponent],
})

Basic usage — a labelled field bound with [(value)]. The value is the string in the field; valueChange fires on every keystroke.

value: "" · 0 valueChange
<div>
  <gog-inputfield
    label="Name"
    placeholder="Ada Lovelace"
    [(value)]="name"
    (valueChange)="changes.update((n) => n + 1)"
  />
  <code>value: "{{ name() }}" · {{ changes() }} valueChange</code>
</div>

Examples

Sizes

Five steps, also settable app-wide through GOG_CONFIG.control.size.

@for (size of sizes; track size) {
  <gog-inputfield [size]="size" [label]="size" placeholder="Placeholder" />
}

States

Default, disabled, readonly and with an error. readonly keeps the field focusable and its text selectable; disabled takes it out of the tab order and dims the whole field — label, box, icons and addons — as one piece 21.15.0.

Required field
<gog-inputfield label="Default" placeholder="Placeholder" />
<gog-inputfield label="Disabled" value="Value" disabled />
<!-- readonly: focusable and selectable, but not editable. -->
<gog-inputfield label="Readonly" value="Value" readonly />
<gog-inputfield label="Error" errorMessage="Required field" />

Types

type is forwarded to the native input, so each of these brings the browser's own keyboard, validation and pickers — the date and time types render the native picker. password and number gain the library's own controls, below.

@for (type of types; track type.type) {
  <gog-inputfield [type]="type.type" [label]="type.type" [placeholder]="type.placeholder" />
}

Icons

iconStart / iconEnd take a bare icon name — the common case, and the whole API for a decorative icon: it renders an aria-hidden span, never a button.

<!-- A bare icon name: decorative, an aria-hidden span, never a button. -->
<gog-inputfield label="Search" iconStart="search" placeholder="Search…" />
<gog-inputfield label="Favourite" iconEnd="star" placeholder="Item" />

Addons

For anything more than an icon name, project a gogInputAddonStart or gogInputAddonEnd element. Because it takes arbitrary markup, an actionable addon is a real <button> with its own aria-label and (click) — nothing threaded through the field. The field measures each addon and makes room for it 21.15.0, so a wide one like https:// no longer runs under the typed text.

$USD
https://
No search yet.
<gog-inputfield label="Amount" [(value)]="amount">
  <span gogInputAddonStart>$</span>
  <span gogInputAddonEnd>USD</span>
</gog-inputfield>

<!-- The field makes room for an addon wider than an icon. -->
<gog-inputfield label="Website" [(value)]="website">
  <span gogInputAddonStart>https://</span>
</gog-inputfield>

<!-- An actionable addon is a real button with its own name and click. -->
<div>
  <gog-inputfield label="Search" [(value)]="search">
    <button type="button" gogInputAddonEnd aria-label="Run search" (click)="run()">
      <gog-icon name="search" />
    </button>
  </gog-inputfield>
  <code>{{ lastSearch() }}</code>
</div>

Clearable

The built-in clear button is value-driven: it appears once there is something to clear and goes when there is not — replacing the hand-rolled trailing-icon-plus-callback pattern.

<!-- Appears once there is something to clear, and goes when there is not. -->
<gog-inputfield label="Name" clearable [(value)]="name" />
<gog-inputfield label="Empty" placeholder="Type to see it" clearable />

Password

type="password" gets a show/hide toggle; its icon and accessible label switch with the state. The toggle keeps the outer edge, and an iconEnd or a gogInputAddonEnd renders beside it 21.15.0 — before, either was silently dropped.

PIN
<gog-inputfield type="password" label="Password" value="secret" />
<!-- The reveal toggle keeps the outer edge; iconEnd or an addon sits beside it. -->
<gog-inputfield type="password" label="With iconEnd" iconEnd="lock" value="secret" />
<gog-inputfield type="password" label="With an addon" value="secret">
  <span gogInputAddonEnd>PIN</span>
</gog-inputfield>

Number — the stepper

A type="number" field draws the library's own +/−, so they follow the theme and are the same size in every browser; at min or max the button for that direction is disabled. [showSpinButtons]="false" removes them, and the field still steps with the arrow keys and the wheel — that is native behaviour. clearable and the stepper coexist: the clear button sits inside the stepper and the gutter widens for both.

<gog-inputfield type="number" label="Stepper" value="5" />
<!-- The arrow keys and the wheel still step: that is native number-input behaviour. -->
<gog-inputfield type="number" label="No stepper" [showSpinButtons]="false" value="5" />
<!-- At a bound the button for that direction is disabled. -->
<gog-inputfield
  type="number"
  label="At max (0–10, step 2)"
  [min]="0"
  [max]="10"
  [step]="2"
  value="10"
/>
<gog-inputfield
  type="number"
  label="At min (0–10, step 2)"
  [min]="0"
  [max]="10"
  [step]="2"
  value="0"
/>
<gog-inputfield type="number" label="Clearable and stepper" clearable value="5" />

Number — beside the stepper

The stepper keeps the outer edge, and an iconEnd or a unit addon sits beside it 21.15.0. The clear button still takes that place while there is a value to clear, as on every field.

kg
<gog-inputfield type="number" label="iconEnd" iconEnd="star" value="5" />
<gog-inputfield type="number" label="Unit" value="5">
  <span gogInputAddonEnd>kg</span>
</gog-inputfield>
<!-- While there is a value, the clear button takes the place beside the stepper. -->
<gog-inputfield type="number" label="Clear wins" clearable iconEnd="star" value="5" />

Number and date values

Through a formControl a number field's value is a real number (null when empty). [(value)] always hands back the string in the field — for a date, the native yyyy-MM-dd.

3 (number)
"" (string)
<!-- Through a formControl a number field's value is a number (null when empty). -->
<div>
  <gog-inputfield label="Quantity" type="number" [min]="1" [max]="10" [formControl]="quantity" />
  <code>{{ quantity.value }} ({{ typeOf(quantity.value) }})</code>
</div>
<!-- [(value)] always hands back the string. -->
<div>
  <gog-inputfield label="Delivery date" type="date" [(value)]="delivery" />
  <code>"{{ delivery() }}" ({{ typeOf(delivery()) }})</code>
</div>

Float label

floatLabel rests the label inside the field like a placeholder and floats it on focus or once there is content. in stays inside the border, on centres on the top border, over floats fully above — each shown empty, then with a value. floatLabelShowPlaceholder brings the placeholder back under the floated label.

@for (variant of variants; track variant) {
  <gog-inputfield
    [floatLabel]="variant"
    [label]="'floatLabel: ' + variant"
    placeholder="e.g. Ada"
  />
  <gog-inputfield [floatLabel]="variant" [label]="'floatLabel: ' + variant" value="Ada Lovelace" />
}

<!-- The placeholder shows under the floated label once it has somewhere to float to. -->
<gog-inputfield
  floatLabel="over"
  floatLabelShowPlaceholder
  label="floatLabelShowPlaceholder"
  placeholder="e.g. Ada"
/>

Error message

errorDisplay="manual", the default, shows errorMessage for as long as it is non-empty — you own the timing. Type one or two characters.

<!-- errorDisplay="manual" (the default): the message shows while it is non-empty. -->
<gog-inputfield
  label="Username"
  [(value)]="username"
  [errorMessage]="username().length > 0 && username().length < 3 ? 'At least 3 characters' : ''"
/>

Reactive forms

Wire it with [formControl] instead of [(value)]. With errorDisplay="auto" the error shows once the control is touched and invalid — leave the empty field to see it. Disabling the control disables the field.

value: "" · touched: false · disabled: false
<div>
  <gog-inputfield
    label="Email (reactive form)"
    placeholder="[email protected]"
    [formControl]="control"
    errorMessage="Enter a valid email"
    errorDisplay="auto"
  />
  <div>
    <gog-button variant="outline" size="sm" (gogClick)="control.markAsTouched()">
      markAsTouched()
    </gog-button>
    <gog-button variant="outline" size="sm" (gogClick)="toggleDisabled()">
      {{ control.disabled ? 'enable()' : 'disable()' }}
    </gog-button>
  </div>
  <code>
    value: "{{ control.value }}" · touched: {{ control.touched }} · disabled: {{ control.disabled }}
  </code>
</div>

Width

Fields fill their container by default — the dashed box here. [fullWidth]="false" shrinks the field to a text input's own width.

<gog-inputfield label="fullWidth (default)" placeholder="Fills the container" />
<gog-inputfield label='[fullWidth]="false"' [fullWidth]="false" placeholder="00000" />

App-wide defaults — GOG_CONFIG

control.size, control.clearable and floatLabel.variant set the defaults for every field under the provider; an instance's own input still wins. In an app the provider goes in app.config.ts — see Global Configuration.

<gog-inputfield label="Size and float label from the config" placeholder="Placeholder" />
<gog-inputfield label='size="sm" — the instance wins' size="sm" placeholder="Placeholder" />
<!-- control.clearable: every field gets a clear button without asking. -->
<gog-inputfield label="Clearable from the config" value="42" />

Accessibility

gog-inputfield renders a native <input> wired to its <label>, so the platform supplies the role, the keyboard and the name.

  • Name — label. A field with no visible label of its own takes your <label for> through inputId; there is no ariaLabel input, so a nameless field cannot be shipped by accident.
  • Error — errorMessage sets aria-invalid="true" and links the message with aria-describedby.
  • Input hints — inputMode, autocomplete and spellcheck are forwarded to the native input.
  • Its own buttons — the stepper, clear and reveal buttons are named by incrementLabel, decrementLabel, clearAriaLabel and the show/hide labels, or GOG_CONFIG.labels. A stepper button at its bound is disabled.

API Reference

Inputs

NameTypeDefaultDescription
showSpinButtonsboolean | undefinedundefinedWhether a type="number" field shows the library's own +/- glyphs in place of the browser's native ones. Off, the field still steps with the arrow keys and the mouse wheel — that is native behaviour, unrelated to which glyphs are visible. Unset, falls back to GOG_CONFIG.inputfield.showSpinButtons, then to true.
incrementLabel / decrementLabelstring | undefined'Increment' / 'Decrement'Accessible names for the two spin buttons. Also via GOG_CONFIG.labels.
readonlybooleanfalseBlocks edits while keeping the value focusable, selectable and submitted with the form. Hides both the clear button and the stepper.
maxlengthnumber | nullnullNative maxlength attribute.
minlengthnumber | nullnullNative minlength attribute.
patternstring''Native pattern attribute — a regular expression source, not a literal.
inputModeGogInputMode | nullnullOn-screen keyboard hint ('numeric', 'tel', 'decimal', …). Worth setting on a numeric field so a phone offers the right keypad.
spellcheckboolean | nullnullNative spellcheck attribute. Unset leaves the browser's own default in place.
valuestring (model)''Two-way bindable value via [(value)]. Always a string — even for type="number" — since it mirrors the native input's raw text. Also the value Angular Forms drives through writeValue/registerOnChange when used with formControlName/[formControl]/ngModel; there, a number field's value is a number (null when empty) instead.
labelstring''Field label.
placeholderstring''Native placeholder text.
type'text' | 'password' | 'email' | 'number' | 'date''text'Native input type. password gets a built-in show/hide toggle for free.
min / max / stepnumber | nullnullOnly applied when type="number" — forwarded to the native min/max/step attributes.
autocompletestring''Forwarded to the native input. Defaults to 'current-password' for password fields, 'off' otherwise, when left empty.
errorMessagestring''Error text to display. Visibility is governed by errorDisplay.
errorDisplay'auto' | 'manual''manual''manual': shown for as long as errorMessage is non-empty — you decide the timing. 'auto': shown once the attached FormControl is touched and invalid; falls back to manual without one.
namestring''Native name attribute.
inputIdstring''id on the native input, and target of the label's for attribute.
disabledbooleanfalseDisables the native input.
size'xsm' | 'sm' | 'md' | 'lg' | 'slg''md'Field height, padding, and font size.
fullWidthbooleantrueFills its container by default. Set false to shrink to content width instead.
iconStart / iconEndGogIconName | ''''Leading / trailing icon name.
clearablebooleanGOG_CONFIG.control.clearable ?? falseAdds a clear button. It appears only once the field has something to clear and disappears again when empty, so it adds no permanent chrome. On a password field the built-in reveal toggle keeps the trailing slot.
clearAriaLabelstring'Clear'Accessible name for that clear button.
floatLabel'none' | 'in' | 'on' | 'over'GOG_CONFIG.floatLabel.variant ?? 'none'Rests the label inside the field like a placeholder and floats it up on focus or once the field has content. 'in' stays inside the border, 'on' centres on the top border line, 'over' floats fully above it.
floatLabelShowPlaceholderbooleanGOG_CONFIG.floatLabel.showPlaceholder ?? falseReveals the field’s own placeholder once the label has floated out of the way. Off by default, since the resting label already occupies that space.
showPasswordLabel / hidePasswordLabelstring'Show password' / 'Hide password'Accessible labels for the built-in password reveal toggle.

Outputs

NamePayloadDescription
valueChangestringEmitted on every edit. Comes from the value model input.

Content slots

DirectiveContextDescription
[gogInputAddonStart]—Arbitrary markup in the leading slot — text, an icon, or a real button.
[gogInputAddonEnd]—The same in the trailing slot. On type="password" and type="number" it renders beside the reveal toggle or the stepper, which keep the outer edge. The clear button, while it shows, outranks it.

Test hooks

The field's own buttons carry data-gog-part21.15.0 — increment, decrement, clear and password-toggle — so a test or an automation script can find them with [data-gog-part="clear"]. Prefer it to the internal gog-input__* classes, which may change.

Global Configuration

Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.

  • GOG_CONFIG.control.size
  • GOG_CONFIG.control.errorDisplay
  • GOG_CONFIG.control.clearable
  • GOG_CONFIG.floatLabel.variant
  • GOG_CONFIG.floatLabel.showPlaceholder
  • GOG_CONFIG.inputfield.showSpinButtons
  • GOG_CONFIG.labels.clear
  • GOG_CONFIG.labels.increment — type="number" spin buttons
  • GOG_CONFIG.labels.decrement — type="number" spin buttons
  • GOG_CONFIG.labels.showPassword
  • GOG_CONFIG.labels.hidePassword

Styling Tokens

Every CSS custom property the input field paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

TokenDescription
--gog-input-label-color / -label-font-family / -label-font-size / -label-font-weight / -label-letter-spacing / -label-line-height / -label-text-transformField label. Each aliases its --gog-field-label-* counterpart.
--gog-input-field-bg / -field-border / -field-colorField surface, border and text.
--gog-input-radiusField corner radius.
--gog-input-focus-border / -focus-ring / -focus-glowFocus state.
--gog-input-error-colorValidation error color.
--gog-input-icon-color / -icon-hover-colorPrefix / suffix icon color.
--gog-input-float-label-reserve / -in-top / -on-bg / -over-gap / -over-reserveFloat-label geometry, derived from the shared --gog-field-float-label-* scale. -on-bg is an instance-layer token (undeclared) — the patch that masks the border behind an "on" label.
--gog-textarea-clear-icon-ratioSize of gog-textarea’s clear glyph relative to the field. A textarea is a large multi-line box, so it takes a full-size glyph rather than the dropdowns’ denser 0.7 ratio.
--gog-textarea-scrollbar-widthInstance-layer (undeclared): written by the component from its own measured scrollbar width, so a clear button on a scrolling textarea does not end up under the thumb.