Text Input

import {TextInputModule} from "@qualcomm-ui/angular/text-input"

Examples

Simple

The simple API bundles all subcomponents together into a single component.

Brand

Label

Optional hint

<q-text-input
  class="w-72"
  hint="Optional hint"
  label="Label"
  placeholder="Placeholder text"
/>

Icons

Add icons using icon props at the root.

Brand

Both icons

<q-text-input
  class="w-72"
  defaultValue="Both icons"
  endIcon="Calendar"
  label="Both icons"
  startIcon="AArrowDown"
/>

Child Directives

Provide child directives to customize specific elements while keeping the simple API's default structure.

Brand

Label

Optional hint

Composite

Build with the composite API for granular control. This API requires you to provide each subcomponent, but gives you full control over the structure and layout.

Brand

Label

Optional hint

<div class="w-72" q-text-input-root>
  <label q-text-input-label>Label</label>
  <div q-text-input-input-group>
    <input placeholder="Placeholder text" q-text-input-input />
    <button q-text-input-clear-trigger></button>
    <span q-text-input-error-indicator></span>
  </div>
  <div q-text-input-hint>Optional hint</div>
  <div q-text-input-error-text>Error text</div>
</div>

Icons (Composite)

The q-text-input-input-group directive provides icon properties for the composite API.

Brand

Start + End icons

<div
  class="w-72"
  defaultValue="Both icons with clear button"
  q-text-input-root
>
  <label q-text-input-label>Start + End icons</label>
  <div endIcon="Calendar" q-text-input-input-group startIcon="AArrowDown">
    <input placeholder="Placeholder text" q-text-input-input />
    <button q-text-input-clear-trigger></button>
  </div>
</div>

Composite Layout

The composite API is useful for alternative layouts and styles.

Brand

Project Name

Project Version

<div q-text-input-root size="sm">
  <div class="flex items-center gap-4">
    <label class="font-body-sm-bold w-48" q-text-input-label>
      Project Name
    </label>
    <div q-text-input-input-group>
      <input class="w-full" placeholder="QVSCE" q-text-input-input />
    </div>
  </div>
</div>

<div q-text-input-root size="sm">
  <div class="flex items-center gap-4">
    <label class="font-body-sm-bold w-48" q-text-input-label>
      Project Version
    </label>
    <div q-text-input-input-group>
      <input class="w-full" placeholder="v1.2.3" q-text-input-input />
    </div>
  </div>
</div>

Clear Trigger

When using the simple API, the clear button renders automatically. Change this by setting the clearable prop to false.
When using the composite API, you render the q-text-input-clear-trigger declaratively within the input group.
The clear button only shows when the input field has text.

Brand

<q-text-input defaultValue="Simple" />

<div defaultValue="Composite" q-text-input-root>
  <div q-text-input-input-group>
    <input q-text-input-input />
    <button q-text-input-clear-trigger></button>
  </div>
</div>

Sizes

Customize size using the size prop. The default size is md.

Brand

<q-text-input
  class="w-56"
  defaultValue="sm"
  size="sm"
  startIcon="Search"
/>
<q-text-input
  class="w-60"
  defaultValue="md"
  size="md"
  startIcon="Search"
/>
<q-text-input
  class="w-64"
  defaultValue="lg"
  size="lg"
  startIcon="Search"
/>

Error Text and Indicator

Error messages are displayed using two props:

invalid
errorText (or the q-text-input-error-text directive when using the composite API)

The error text and indicator will only render when invalid is true.

Brand

Label

You must enter a value

<q-text-input
  #textInput
  class="w-64"
  errorText="You must enter a value"
  label="Label"
  placeholder="Enter a value"
  required
  [invalid]="!value()"
  [(ngModel)]="value"
/>

Forms

Control and validate the input value using Angular form control bindings.

Template Forms

When using template-driven forms with ngModel, perform validation manually in your component and pass the result to the invalid property.

TIP

Form validation timing is controlled by the updateOn property on the form control.

Brand

Label

<q-text-input
  class="w-72"
  errorText="Must be at least 3 characters long"
  label="Label"
  placeholder="Enter a value"
  [invalid]="value().length < 2"
  [(ngModel)]="value"
/>

States

When using template forms, the disabled, readOnly, and invalid properties govern the interactive state of the control.

Brand

Disabled

Read only

Invalid

<q-text-input disabled label="Disabled" placeholder="Disabled" />
<q-text-input label="Read only" placeholder="Read only" readOnly />
<q-text-input
  errorText="Invalid"
  invalid
  label="Invalid"
  placeholder="Invalid"
/>

Required

When using template forms, pass the required property to apply the RequiredValidator to the form control.

Brand

Required

<q-text-input
  class="w-72"
  label="Required"
  placeholder="Enter a value"
  required
  [(ngModel)]="value"
/>

Reactive Forms

Use Reactive Forms for better control of form state and validation.

Brand

State Guidelines

The disabled, invalid, and required properties have no effect when using Reactive Forms. Use the equivalent Reactive Form bindings instead:

Brand

Disabled

Invalid

Required

disabledField = new FormControl("")
invalidField = new FormControl("invalid-email", {
  validators: [Validators.required, Validators.email],
})
requiredField = new FormControl("", {validators: [Validators.required]})

ngOnInit() {
  this.disabledField.disable()
  this.invalidField.markAsDirty()
}

Composite API & Forms

When using the composite API with Angular Forms, always apply form control bindings to the q-text-input-root directive.

Brand

Composite Forms

<div
  class="w-72"
  q-text-input-root
  [invalid]="isInvalid()"
  [(ngModel)]="value"
>
  <label q-text-input-label>Composite Forms</label>
  <div q-text-input-input-group>
    <input placeholder="Enter a value" q-text-input-input />
    <button q-text-input-clear-trigger></button>
    <span q-text-input-error-indicator></span>
  </div>
  <div q-text-input-error-text>Must be at least three characters long</div>
</div>

API

<q-text-input>

The <q-text-input> component extends the q-text-input-root directive with the following properties:

Groups all parts of the text input.

Prop	Type	Default
clearable When `true`, renders a clear button that resets the input value on click. The button only appears when the input has a value.	boolean	true
errorText Optional error that describes the element when invalid is true.	string

hint Optional hint describing the element. This element is automatically associated with the component's input element for accessibility.	string

label Optional label describing the element. Recommended. This element is automatically associated with the component's input element for accessibility.	string

placeholder HTML placeholder attribute, passed to the internal input element.	string

clearable

Type

boolean

Description

When true, renders a clear button that resets the input value on click. The button only appears when the input has a value.

errorText

Type

string

Description

Optional error that describes the element when invalid is true.

hint

Type

string

Description

Optional hint describing the element. This element is automatically associated with the component's input element for accessibility.

label

Type

string

Description

Optional label describing the element. Recommended. This element is automatically associated with the component's input element for accessibility.

placeholder

Type

string

Description

HTML placeholder attribute, passed to the internal input element.

Prop	Type	Default
defaultValue The initial state of the input when rendered. Use when you don't need to control the checked state of the input. This property will be ignored if you opt into controlled state via form control bindings.	string
dir The document's text/writing direction.	'ltr' \| 'rtl'	"ltr"
disabled Controls whether the input is disabled in template-driven forms. When true, prevents user interaction and applies visual styling to indicate the disabled state.	boolean
endIcon lucide-angular icon, positioned after the input.	\| string \| LucideIconData

getRootNode A root node to correctly resolve the Document in custom environments. i.e., Iframes, Electron.	() => \| Node \| ShadowRoot \| Document
invalid Controls the visual error state of the input. When true, applies semantic error styling to indicate validation failure.	boolean
name The name of the input field. Useful for form submission.	string
readOnly Whether the input is read-only. When true, prevents user interaction while keeping the input focusable and visible.	boolean
required Controls whether the input is required in template-driven forms. When true, the input must have a value for form validation to pass.	boolean
size The size of the input field and its elements. Governs properties like font size, item padding, and icon sizes.	\| 'sm' \| 'md' \| 'lg'	'md'
startIcon lucide-angular icon, positioned before the input.	\| string \| LucideIconData

(valueChanged) Event emitted when the input value changes. This is only emitted on interaction. It doesn't emit in response to programmatic form control changes.	string

The initial state of the input when rendered. Use when you don't need to control the checked state of the input. This property will be ignored if you opt into controlled state via form control bindings.

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

disabled

Type

boolean

Description

Controls whether the input is disabled in template-driven forms. When true, prevents user interaction and applies visual styling to indicate the disabled state.

endIcon

Type

| string
| LucideIconData

Description

lucide-angular icon, positioned after the input.

getRootNode

Type

() =>
| Node
| ShadowRoot
| Document

Description

A root node to correctly resolve the Document in custom environments. i.e., Iframes, Electron.

invalid

Type

boolean

Description

Controls the visual error state of the input. When true, applies semantic error styling to indicate validation failure.

name

Type

string

Description

The name of the input field. Useful for form submission.

readOnly

Type

boolean

Description

Whether the input is read-only. When true, prevents user interaction while keeping the input focusable and visible.

required

Type

boolean

Description

Controls whether the input is required in template-driven forms. When true, the input must have a value for form validation to pass.

size

Type

| 'sm'
| 'md'
| 'lg'

Description

The size of the input field and its elements. Governs properties like font size, item padding, and icon sizes.

startIcon

Type

| string
| LucideIconData

Description

lucide-angular icon, positioned before the input.

(valueChanged)

Type

string

Description

Event emitted when the input value changes. This is only emitted on interaction. It doesn't emit in response to programmatic form control changes.

Attribute / Property	Value
`class`	'qui-input__root'
`data-disabled`
`data-focus`
`data-invalid`
`data-part`	'root'
`data-scope`	'text-input'
`data-size`	\| 'sm' \| 'md' \| 'lg'

class

Value

'qui-input__root'

data-disabled

Value

data-focus

Value

data-invalid

Value

data-part

Value

'root'

data-scope

Value

'text-input'

data-size

Value

| 'sm'
| 'md'
| 'lg'

q-text-input-input-group

Container that wraps the input element and optional icons.

Attribute / Property	Value
`class`	'qui-input__input-group'
`data-disabled`
`data-focus`
`data-invalid`
`data-part`	'input-group'
`data-readonly`
`data-scope`	'text-input'
`data-size`	\| 'sm' \| 'md' \| 'lg'

class

Value

'qui-input__input-group'

data-disabled

Value

data-focus

Value

data-invalid

Value

data-part

Value

'input-group'

data-readonly

Value

data-scope

Value

'text-input'

data-size

Value

| 'sm'
| 'md'
| 'lg'

q-text-input-label

An accessible label that is automatically associated with the input.

Prop	Type
id	string

Type

string

Attribute / Property	Value
`class`	'qui-input__label'
`data-disabled`
`data-focus`
`data-invalid`
`data-part`	'label'
`data-scope`	'text-input'
`data-size`	\| 'sm' \| 'md' \| 'lg'

class

Value

'qui-input__label'

data-disabled

Value

data-focus

Value

data-invalid

Value

data-part

Value

'label'

data-scope

Value

'text-input'

data-size

Value

| 'sm'
| 'md'
| 'lg'

q-text-input-hint

Helper text displayed below the input.

Prop	Type
id	string

Type

string

Attribute / Property	Value
`class`	'qui-input__hint'
`data-disabled`
`data-part`	'hint'
`data-scope`	'text-input'

q-text-input-clear-trigger

Button that clears the input value.

Attribute / Property	Value
`class`	'qui-input__clear-trigger'
`data-disabled`
`data-part`	'clear-trigger'
`data-scope`	'text-input'
`data-size`	\| 'sm' \| 'md' \| 'lg'

class

Value

'qui-input__clear-trigger'

data-disabled

Value

data-part

Value

'clear-trigger'

data-scope

Value

'text-input'

data-size

Value

| 'sm'
| 'md'
| 'lg'

q-text-input-input

The text input element. Note: do not apply form control bindings like ngModel or formControl to this element. Apply them to the root element instead.

Prop	Type
id	string

Type

string

Attribute / Property	Value
`class`	'qui-input__input'
`data-empty`
`data-focus`
`data-invalid`
`data-part`	'input'
`data-readonly`
`data-scope`	'text-input'
`data-size`	\| 'sm' \| 'md' \| 'lg'

class

Value

'qui-input__input'

data-empty

Value

data-focus

Value

data-invalid

Value

data-part

Value

'input'

data-readonly

Value

data-scope

Value

'text-input'

data-size

Value

| 'sm'
| 'md'
| 'lg'

q-text-input-error-text

Error message displayed when the input is invalid.

Prop	Type
icon Optional error indicator icon.	\| string \| LucideIconData
id	string

icon

Type

| string
| LucideIconData

Description

Optional error indicator icon.

Type

string

Attribute / Property	Value
`class`	'qui-input__error-text'
`data-part`	'error-text'
`data-scope`	'text-input'
`hidden`	boolean

class

Value

'qui-input__error-text'

data-part

Value

'error-text'

data-scope

Value

'text-input'

hidden

Value

boolean

q-text-input-error-indicator

Visual indicator displayed when the input is invalid.

Prop	Type	Default
icon lucide-angular icon	\| LucideIconData \| string	CircleAlert

icon

Type

| LucideIconData
| string

Description

lucide-angular icon

Attribute / Property	Value
`class`	'qui-input__error-indicator'
`data-part`	'error-indicator'
`data-scope`	'text-input'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`hidden`	boolean

class

Value

'qui-input__error-indicator'

data-part

Value

'error-indicator'

data-scope

Value

'text-input'

data-size

Value

| 'sm'
| 'md'
| 'lg'

hidden

Value

boolean

Switch

Avatar