GUILD OF GLEKS UIv21.19.0

gog-textarea

Text Area

A multi-line counterpart to gog-inputfield, sharing its five sizes, its tokens, error handling and full ControlValueAccessor support, with a themed resize grip of its own.

Overview

Import the component and drop it into a template.

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

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

Basic usage — a labeled field bound with [(value)]:

0 characters · 0 valueChange
<div>
  <gog-textarea
    label="Bio"
    placeholder="Tell us about yourself"
    [rows]="3"
    [(value)]="bio"
    (valueChange)="changes.update((n) => n + 1)"
  />
  <code>{{ bio().length }} characters · {{ changes() }} valueChange</code>
</div>

Examples

Sizes

Five steps, the same scale as gog-inputfield; also settable app-wide through GOG_CONFIG.control.size.

@for (size of sizes; track size) {
  <gog-textarea [size]="size" [label]="'size: ' + size" placeholder="Placeholder" [rows]="2" />
}

States

Default, disabled, readonly and with an error. Focus is a pseudo-class, so it is not shown here — tab into any field. readonly blocks edits while the value stays focusable, selectable and submitted with the form.

Required field
<gog-textarea label="Default" placeholder="Placeholder" [rows]="2" />
<gog-textarea label="Disabled" value="Ship on Friday." [rows]="2" disabled />
<!-- Focusable, selectable and submitted with the form; only edits are blocked. -->
<gog-textarea label="Readonly" value="Ship on Friday." [rows]="2" readonly />
<gog-textarea label="Error" placeholder="Placeholder" [rows]="2" errorMessage="Required field" />

Error timing you own

With the default errorDisplay="manual" the message shows for as long as errorMessage is non-empty — the page decides when. Type fewer than ten characters.

<!-- errorDisplay="manual" (the default): shown for as long as errorMessage is non-empty. -->
<gog-textarea
  label="Feedback"
  placeholder="At least 10 characters"
  [rows]="3"
  [(value)]="feedback"
  [errorMessage]="feedback().length > 0 && feedback().length < 10 ? 'At least 10 characters' : ''"
/>

Rows

rows is the native attribute: the field's initial height, before anyone drags the grip.

<gog-textarea label='[rows]="2"' placeholder="Placeholder" [rows]="2" />
<gog-textarea label="rows unset (4)" placeholder="Placeholder" />
<gog-textarea label='[rows]="8"' placeholder="Placeholder" [rows]="8" />

Resize

resize takes the native CSS values — 'vertical' (the default), 'horizontal', 'both', or 'none' for no grip. The grip is the library's own, so it follows the theme instead of showing a browser's corner triangle; the drag underneath it is the browser's. Drag a corner to watch the grip follow. Set it app-wide with GOG_CONFIG.textarea.resize.

<!-- The grip is the library's own; the drag underneath it is the browser's. -->
<gog-textarea label="resize unset (vertical)" value="Ship on Friday." [rows]="2" />
<gog-textarea label='resize="horizontal"' value="Ship on Friday." [rows]="2" resize="horizontal" />
<gog-textarea label='resize="both"' value="Ship on Friday." [rows]="2" resize="both" />
<gog-textarea label='resize="none"' value="Ship on Friday." [rows]="2" resize="none" />
<gog-textarea label="Disabled: no grip" value="Ship on Friday." [rows]="2" disabled />

Clearable

The clear button shows only while there is something to clear, so it adds no permanent chrome. It sits in the field's top end corner and steps clear of the scrollbar once the content overflows — the second field. A readonly field has nothing to clear and shows no button.

<gog-textarea label="One line" value="Ship on Friday." [rows]="4" clearable />
<!-- The button steps clear of the scrollbar once the content overflows. -->
<gog-textarea label="Overflowing" [value]="longText" [rows]="4" clearable />
<gog-textarea
  label="clearAriaLabel"
  value="Ship on Friday."
  [rows]="4"
  clearable
  clearAriaLabel="Erase notes"
/>
<!-- Nothing to clear when nothing can be edited. -->
<gog-textarea label="Readonly: no button" value="Ship on Friday." [rows]="4" clearable readonly />

Width

Fields fill their container by default — the dashed box here. [fullWidth]="false" shrinks the field to its content instead.

<gog-textarea label="fullWidth (default)" placeholder="Fills the container" [rows]="2" />
<gog-textarea
  label='[fullWidth]="false"'
  [fullWidth]="false"
  placeholder="Shrinks to content"
  [rows]="2"
/>

Native attributes

name, maxlength, minlength and spellcheck go straight onto the <textarea>. maxlength stops typing at 72; minlength is the browser's own constraint, not an Angular validator — pair it with Validators.minLength in a form. spellcheck unset leaves the browser's default.

0 characters
<div>
  <gog-textarea
    label="Commit message"
    name="message"
    placeholder="Up to 72 characters"
    [rows]="2"
    [maxlength]="72"
    [spellcheck]="true"
  />
</div>
<div>
  <!-- spellcheck off: a code snippet is not prose. -->
  <gog-textarea label="Snippet" [rows]="2" [spellcheck]="false" [minlength]="3" [(value)]="code" />
  <code>{{ code().length }} characters</code>
</div>

Float label

'none' keeps the label above the field; 'in', 'on' and 'over' rest it on the first line and float it clear on focus or a value — each shown empty, then filled. floatLabelShowPlaceholder brings the placeholder back under the floated label.

@for (variant of variants; track variant) {
  <gog-textarea
    [floatLabel]="variant"
    [label]="'floatLabel: ' + variant"
    placeholder="Anything to add?"
    [rows]="2"
  />
  <gog-textarea
    [floatLabel]="variant"
    [label]="'floatLabel: ' + variant"
    value="Ship on Friday."
    [rows]="2"
  />
}

<!-- The placeholder shows under the floated label once it has somewhere to float to. -->
<gog-textarea
  floatLabel="over"
  floatLabelShowPlaceholder
  label="floatLabelShowPlaceholder"
  placeholder="Anything to add?"
  [rows]="2"
/>

Reactive forms

With errorDisplay="auto" the error shows once the control is touched and invalid — tab in and out of the empty field — instead of the page computing the timing.

0 characters · valid: false · touched: false · disabled: false
<div>
  <gog-textarea
    label="Feedback (reactive form)"
    placeholder="What should we change?"
    [rows]="2"
    [formControl]="control"
    errorMessage="At least 10 characters"
    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>
    {{ control.value.length }} characters · valid: {{ control.valid }} · touched:
    {{ control.touched }} · disabled: {{ control.disabled }}
  </code>
</div>

App-wide defaults — GOG_CONFIG

control.size, control.clearable, floatLabel.variant and textarea.resize 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-textarea label="Size from the config (lg)" placeholder="Placeholder" [rows]="2" />
<gog-textarea
  label='size="sm" — the instance wins'
  size="sm"
  placeholder="Placeholder"
  [rows]="2"
/>
<!-- clearable, no grip and the float label all come from the config. -->
<gog-textarea label="Notes" value="Ship on Friday." [rows]="2" />

Accessibility

A native <textarea>: role, value, editing and the keyboard all come from the platform.

  • Name — the label, through its for. There is no ariaLabel input; a field without a visible label should get one, or a floating one.
  • Keyboard — Tab enters and leaves the field, Enter makes a new line rather than submitting the form. The clear button is its own tab stop and is named by clearAriaLabel, or GOG_CONFIG.labels.clear.
  • State — disabled and readonly are the native attributes, so a screen reader announces them as such.
  • Error — aria-invalid on the textarea and an aria-describedby pointing at the message, which is a role="alert".

API Reference

Inputs

NameTypeDefaultDescription
resize'vertical' | 'horizontal' | 'both' | 'none' | undefinedundefinedWhich direction(s) the field's own drag handle resizes it in — the native CSS resize value space, with 'none' removing the handle entirely. Unset, falls back to GOG_CONFIG.textarea.resize, then to 'vertical'.
readonlybooleanfalseBlocks edits while keeping the value focusable, selectable and submitted with the form. Also hides the clear button.
maxlengthnumber | nullnullNative maxlength attribute.
minlengthnumber | nullnullNative minlength attribute.
spellcheckboolean | nullnullNative spellcheck attribute. Unset leaves the browser's own default in place.
valuestring (model)''Two-way bindable value via [(value)]. Also the value Angular Forms drives through writeValue/registerOnChange when used with formControlName/[formControl]/ngModel.
labelstring''Field label.
placeholderstring''Native placeholder text.
rowsnumber4Native rows attribute, controlling the field's initial height.
errorMessagestring''Error text to display. Visibility is governed by errorDisplay.
errorDisplay'auto' | 'manual'GOG_CONFIG.control.errorDisplay ?? '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. Settable app-wide, which is what makes 'auto' one decision for a Reactive Forms app rather than per-field boilerplate.
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.
clearAriaLabelstringGOG_CONFIG.labels.clear ?? '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. 'none' keeps the static label-above-the-field layout.
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.
namestring''Native name attribute.
inputIdstring''id on the native textarea, and target of the label's for attribute.
disabledbooleanfalseDisables the native textarea.
size'xsm' | 'sm' | 'md' | 'lg' | 'slg'GOG_CONFIG.control.size ?? 'md'Field padding and font size — shares the scale with gog-inputfield.
fullWidthbooleantrueFills its container by default. Set false to shrink to content width instead.

Outputs

NamePayloadDescription
valueChangestringEmitted on every edit, and by the clear button. Comes from the value model input.

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.textarea.resize
  • GOG_CONFIG.labels.clear

Styling Tokens

gog-textarea paints with the same --gog-input-* tokens as gog-inputfield — there's no separate token set to learn. 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.

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.