QdsTextInput

Single-line text entry with built-in validation, form association, and accessibility.

Overview

The qds-text-input component is a form-associated custom element that provides single-line text input. It is the reference implementation for the form-association pattern used by all six QDS form controls. It supports labels, hints, error messages, character counters, clear buttons, prefix/suffix icon slots, and three validation timing modes.

Usage

<qds-text-input label="Full Name" placeholder="Enter your name" required></qds-text-input>

<qds-text-input label="Search" type="search" clearable>
  <i slot="prefix" class="pi pi-search"></i>
</qds-text-input>

<qds-text-input label="Email" type="email" required hint="We will never share your email."></qds-text-input>

API Reference

Attributes

• value - (string) The current value; attribute sets the initial value.
• name - (string) Submitted form key.
• label - (string) Rendered as a real <label for> in the shadow root.
• placeholder - (string) Placeholder text, not a substitute for label.
• hint - (string) Helper text displayed below the input.
• error-text - (string) Overrides the built-in validation message.
• type - ('text' | 'search' | 'email' | 'tel' | 'url' | 'password') Input type, default text.
• size - ('sm' | 'md' | 'lg') Control height, default md.
• disabled - (boolean) Not focusable, not submitted.
• readonly - (boolean) Focusable, submitted, secondary background.
• required - (boolean) Field is required.
• invalid - (boolean) Author-forced invalid state.
• maxlength - (number) Maximum character count.
• minlength - (number) Minimum character count.
• pattern - (string) RegExp pattern for validation.
• autocomplete - (string) Autocomplete hint for the browser.
• show-counter - (boolean) Show character counter (requires maxlength).
• clearable - (boolean) Show a clear button when non-empty.
• validate-on - ('blur' | 'input' | 'submit') Validation timing, default blur.

Properties

• value - (string) Current value, synced with attribute in both directions.
• name - (string) Form field name.
• disabled - (boolean) Whether the control is disabled.
• readonly - (boolean) Whether the control is read-only.
• required - (boolean) Whether the control is required.
• type - (string) Input type.
• size - (string) Control size.
• validity - (QdsValidity) Read-only validity state.
• form - (HTMLFormElement | null) The associated form element.
• checkValidity() - Returns boolean, validates without showing the message.
• reportValidity() - Returns boolean, validates and shows the error message.
• setCustomValidity(msg) - Sets a custom error message; empty string clears it.

CSS Parts

• container - Outer container.
• label - Label element.
• required - Required marker span inside the label.
• wrapper - Input wrapper (border surface).
• input - Inner input element.
• prefix - Prefix slot.
• suffix - Suffix slot.
• clear-button - Clear button.
• hint - Hint text.
• error - Error message.
• counter - Character counter.

CSS Custom Properties

• --qds-input-height - Control height (default var(--qds-control-height-md, 40px)).
• --qds-input-background - Control background (default var(--theme-background-primary)).
• --qds-input-border-color - Resting border color (default var(--theme-border-primary)).
• --qds-input-border-color-hover - Hover border color (default var(--theme-border-secondary)).
• --qds-input-border-color-focus - Focus border color (default var(--theme-accent-primary)).
• --qds-input-radius - Border radius (default var(--theme-radius-sm, 4px)).
• --qds-input-padding-x - Horizontal padding (default var(--theme-space-3, 12px)).

Events

• input - Every keystroke; bubbles, composed.
• change - Value committed (blur or Enter); bubbles, composed.
• qds-validity-change - Validity flips or message changes; detail { component, valid, validity, message }.
• qds-clear - Clear button pressed; detail { component }.

Validation Timing

• validate-on="blur" (default) - Validates on blur. Once an error has been shown, subsequent input re-validates live so the error clears as soon as the value is valid.
• validate-on="input" - Validates on every keystroke.
• validate-on="submit" - Suppresses error display until reportValidity() is called.

Example

<form>
  <qds-text-input
    label="Email Address"
    type="email"
    name="email"
    required
    hint="We will never share your email."
    show-counter
    maxlength="100"
    clearable
  >
    <i slot="prefix" class="pi pi-envelope"></i>
  </qds-text-input>
  <button type="submit">Submit</button>
</form>