Input

The Input element is used to create interactive controls for forms in order to accept data from the user; a wide variety of types of input data and control widgets are available.

— Definition from the MDN web docs

Types

The type attribute controls the type of input the browser renders. Most of the native browser types are supported, but not all.

In Figma, each input type is a standalone component named qds-input • type=<type>.

Text

The text input type lets the user enter text. This is the default input type.

Use the minlength and maxlength attributes to constrain the length of the user entry.

Live Editor

<label class="qds-controls qds-related flex-row">
  <qds-label inline text="First name:"></qds-label>
  <qds-input
    minlength="2"
    maxlength="20"
    autocomplete="cc-given-name"
  ></qds-input>
</label>

See the <input type="text"> MDN documentation for an in-depth introduction.

Number

The number input type lets the user enter numerical data only.

Use the min and max attributes to define the range of valid values:

Live Editor

<label class="qds-controls qds-related flex-row">
  <qds-label inline text="Enter a single digit:"></qds-label>
  <qds-input type="number" min="0" max="9"></qds-input>
</label>

By default, number inputs allow integers only. Use the step attribute to define the granularity to which the value must adhere:

Live Editor

<div class="qds-controls qds-related">
  <label class="qds-controls qds-related flex-row">
    <qds-label inline text="Enter a positive integer:"></qds-label>
    <qds-input type="number" min="0"></qds-input>
  </label>
  <label class="qds-controls qds-related flex-row">
    <qds-label inline text="Enter a multiple of 10:"></qds-label>
    <qds-input type="number" min="0" step="10"></qds-input>
  </label>
  <label class="qds-controls qds-related flex-row">
    <qds-label inline text="Enter a decimal value:"></qds-label>
    <qds-input type="number" min="0" step="0.1"></qds-input>
  </label>
</div>

See the <input type="number"> MDN documentation for an in-depth introduction.

Date and time

The input component supports several formats of date and time entry:

date: a single date
time: a single time
datetime-local: a specific point in time (date + time)
month: a single month
week: a single week

The browser follows the user's preferences to display dates and times in his local format.

Live Editor

<div class="qds-controls qds-related">
  <label class="qds-controls qds-related flex-row">
    <qds-label inline text="Date:"></qds-label>
    <qds-input type="date"></qds-input>
  </label>
  <label class="qds-controls qds-related flex-row">
    <qds-label inline text="Time:"></qds-label>
    <qds-input type="time"></qds-input>
  </label>
  <label class="qds-controls qds-related flex-row">
    <qds-label inline text="Date and time:"></qds-label>
    <qds-input type="datetime-local"></qds-input>
  </label>
  <label class="qds-controls qds-related flex-row">
    <qds-label inline text="Month:"></qds-label>
    <qds-input type="month"></qds-input>
  </label>
  <label class="qds-controls qds-related flex-row">
    <qds-label inline text="Week:"></qds-label>
    <qds-input type="week"></qds-input>
  </label>
</div>

Email

The email input type lets the user enter a valid email address:

Live Editor

<label class="qds-controls qds-related flex-row">
  <qds-label inline text="Enter your email:"></qds-label>
  <qds-input type="email" autocomplete="email"></qds-input>
</label>

Use the minlength and maxlength attributes to constrain the length of the user entry.

Set the multiple attribute to allow the user to enter several email addresses separated by commas:

Live Editor

<label class="qds-controls qds-related flex-row">
  <qds-label inline text="Emails separated by commas:"></qds-label>
  <qds-input class="flex-1" type="email" multiple value="a@se.com, b@se.com, c@se.com" autocomplete="email"></qds-input>
</label>

The browser takes care of validating the user entry, but you can customize it using the pattern attribute (see Custom format).

See the <input type="email"> MDN documentation for an in-depth introduction.

Password

The password input type lets the user securely type a password:

Live Editor

<label class="qds-controls qds-related flex-row">
  <qds-label inline text="Password:"></qds-label>
  <qds-input type="password" autocomplete="new-password"></qds-input>
</label>

Set the autocomplete attribute to give hints to the browser about which password should be proposed:

Live Editor

<div class="qds-controls qds-related">
  <label class="qds-controls qds-related flex-row">
    <qds-label inline text="Current password:"></qds-label>
    <qds-input type="password" autocomplete="current-password"></qds-input>
  </label>
  <label class="qds-controls qds-related flex-row">
    <qds-label inline text="New password:"></qds-label>
    <qds-input type="password" autocomplete="new-password"></qds-input>
  </label>
  <label class="qds-controls qds-related flex-row">
    <qds-label inline text="Re-enter new password:"></qds-label>
    <qds-input type="password" autocomplete="new-password"></qds-input>
  </label>
</div>

Use the minlength and maxlength attributes to constrain the length of the user entry.

You can also customize the password format using the pattern attribute (see Custom format). When doing so, you may indicate the expected type of input using the inputmode attribute to tell the browser to display the appropriate virtual keyboard on mobile devices:

Live Editor

<label class="qds-controls qds-related flex-row">
  <qds-label inline text="Enter your 6-digit code:"></qds-label>
  <qds-input type="password" pattern="[0-9]{6}" inputmode="numeric"></qds-input>
</label>

See the <input type="password"> MDN documentation for an in-depth introduction.

Search

The search input type behaves like a text input and displays a magnifying glass icon:

Live Editor

<label class="qds-controls qds-related flex-row">
  <qds-label inline text="Search:"></qds-label>
  <qds-input type="search"></qds-input>
</label>

As it carries a specific meaning, the browsers often add specific behaviors:

remember the last entered search terms
display a cross icon to clear the contents of the search field

See the <input type="search"> MDN documentation for an in-depth introduction.

Telephone

The tel input type behaves like a text field and displays a specialized virtual keyboard on mobile devices.

Live Editor

<label class="qds-controls qds-related flex-row">
  <qds-label inline text="Phone number:"></qds-label>
  <qds-input type="tel" autocomplete="tel"></qds-input>
</label>

However, unlike email and url types, the input value is not automatically validated to a particular format before the form can be submitted, because formats for telephone numbers vary so much around the world. See the Custom format section to learn how to specify and validate custom formats.

See the <input type="tel"> MDN documentation for an in-depth introduction.

URL

The url input type lets the user enter and edit a URL:

Live Editor

<label class="qds-controls qds-related flex-row">
  <qds-label inline text="Website URL:"></qds-label>
  <qds-input type="url" autocomplete="url"></qds-input>
</label>

As [URLs can take many different forms][], you should specify a more restrictive URL format when possible. See the Custom format section to learn how to specify and validate custom formats.

For example:

Live Editor

<label class="qds-controls qds-related flex-row">
  <qds-label inline text="Website URL:"></qds-label>
  <qds-input type="url" pattern="" autocomplete="url"></qds-input>
</label>

See the <input type="url"> MDN documentation for an in-depth introduction.

Color

The color input type provides a user interface element that lets a user specify a color:

Live Editor

<label class="qds-controls qds-related flex-row">
  <qds-label inline text="Favorite color:"></qds-label>
  <qds-input type="color" autocomplete="on"></qds-input>
</label>

Note that the color selector presentation varies substantially from one browser and/or platform to another.

See the <input type="color"> MDN documentation for an in-depth introduction.

Size

Inputs follow the transversal control size principles. Use the standard size unless you're in one of the specific contexts described on that page.

Live Editor

<div class="qds-controls qds-related">
  <div class="qds-controls qds-related flex flex-row">
    <qds-label inline text="Standard size:"></qds-label>
    <qds-input></qds-input>
  </div>
  <div class="qds-controls-large qds-related flex flex-row">
    <qds-label inline size="large" text="Large size:"></qds-label>
    <qds-input size="large"></qds-input>
  </div>
  <div class="qds-controls-small qds-related flex flex-row">
    <qds-label inline size="small" text="Small size:"></qds-label>
    <qds-input size="small"></qds-input>
  </div>
</div>

NoIcon

In some contexts, the input type icon (ex: magnifying glass for search type) is redundant or added in a button next to the field. The no-icon attribute will allow this icon to be hidden when needed.

Live Editor

<div className="qds-control-group qds-related flex flex-col">
  <div className="qds-control-group-inline flex items-center">
    <label>
      <span className="sr-only">Search</span>
      <qds-input type="search" placeholder="Search" no-icon></qds-input>
    </label>
    <qds-button
      importance="emphasized"
      icon-library="core"
      icon-name="input-search"
    ></qds-button>
  </div>
</div>

Layout

Always display a label near the input field:

Live Editor

<div class="qds-controls">
  <label class="qds-controls qds-related flex-row">
    <qds-label inline text="Inline label:"></qds-label>
    <qds-input></qds-input>
  </label>
  <label class="qds-controls qds-related">
    <qds-label text="Stacked label:"></qds-label>
    <qds-input></qds-input>
  </label>
</div>

See the Label component documentation for detailed instructions on how to properly implement this.

In forms

Follow the Forms design pattern guidelines to properly organize and space your form labels and controls.

Additional options

Spellchecking

Set spellcheck="true" to force the browser to enable spellchecking on the input field:

Live Editor

<label class="qds-controls qds-related flex-row">
  <qds-label inline text="Favorite fruit:"></qds-label>
  <qds-input
    spellcheck="true"
    value="Dargon fruit"
    autocomplete="on"
  ></qds-input>
</label>

See the <input type="text"> MDN documentation for an in-depth introduction to patterns.

Required

Set the required attribute on an input to force the user to enter data before validating the form.

You should also set the required attribute of the associated <qds-label> element to offer a visual cue to the user that the input is required.

Live Editor

<form class="qds-controls qds-related">
  <label class="qds-controls qds-related flex-row">
    <qds-label inline required text="First name:"></qds-label>
    <qds-input required autocomplete="cc-family-name"></qds-input>
  </label>
  <qds-button text="Submit"></qds-button>
</form>

Placeholder

Use the placeholder attribute to add a placeholder:

Live Editor

<qds-input placeholder="Type something"></qds-input>

Disabled

Use the disabled attribute to disable an input.

Live Editor

<qds-input placeholder="Disabled" disabled></qds-input>

Implementation tips

Custom width

Inputs have a default size, depending on their type. Use the width CSS property as you usually do to set a custom width.

For example, you can use the flex-1 utility class from our Tailwind preset:

Live Editor

<div class="qds-controls flex-row w-full">
  <label class="qds-controls qds-related flex-row w-full">
    <qds-label inline text="First name:"></qds-label>
    <qds-input class="flex-1" autocomplete="cc-given-name">
      >
    </qds-input>
  </label>
  <label class="qds-controls qds-related flex-row w-full">
    <qds-label inline text="Last name:"></qds-label>
    <qds-input class="flex-1" autocomplete="family-name"></qds-input>
  </label>
</div>

Or you can use the w-full utility class for mobile display:

Live Editor

<div class="qds-controls qds-related">
  <qds-label text="First name:"></qds-label>
  <qds-input
    text="Full width"
    class="w-full"
    autocomplete="cc-given-name"
  ></qds-input>
</div>

Custom format

Use the pattern attribute to specify a regular expression that the input value must match to be considered valid:

Live Editor

<label class="qds-controls qds-related">
  <qds-label text="Username:"></qds-label>
  <qds-input pattern="[A-Za-z0-9-]{3,20}" autocomplete="username"></qds-input>
  <small>3 to 20 alphanumeric characters or hyphens</small>
</label>

Note that the pattern is used only for validating the input. Setting a validation pattern does not show any visual clue to the user, and it does not restrict the data entry on the keyboard.

Use the [Form message][form-message] component to inform the user of the expected entry format.

See the pattern attribute MDN documentation for an in-depth introduction to patterns.

Importing

Note: if you're using the lazy loader to load Quartz components, you can ignore this section.

Import
Bundler
Angular
React
Vue

To import this component from the public jsDeliver CDN using a JavaScript import:

import { defineCustomElementQdsInput } from 'https://cdn.jsdelivr.net/npm/@quartzds/core@next+esm'
defineCustomElementQdsInput()

To import this component using a bundler:

import { defineCustomElementQdsInput } from '@quartzds/core'
defineCustomElementQdsInput()

To import this component as an Angular component:

import { QdsInput } from '@quartzds/core-angular'

To import this component as a React component:

import { QdsInput } from '@quartzds/core-react'

To import this component as a Vue component:

import { QdsInput } from '@quartzds/core-vue'

Accessibility

All input fields should have visible labels provided by <qds-label>. For <qds-input type="search">, you can use the sr-only class from Tailwind to add a label that will be hidden visually but accessible to screen readers. This ensures that the input field remains accessible while maintaining a clean visual design.
It is recommended to add instructions and error messages to the input when needed.
It is recommended to use the autocomplete attribute when collecting user data to improve form usability and support browser-based autofill.
For more guidelines, please check Input types patterns.

Component reference

Properties

Attribute / Property

Type

Description

Default

autocapitalize / autoCapitalize

Controls whether and how input is automatically capitalized as it is entered/edited by the user. Only valid for search, tel, and text inputs. Possible values:

"off" or "none": No auto-capitalization is applied (all letters default to lowercase).
"on" or "sentences": The first letter of each sentence defaults to a capital letter; all other letters default to lowercase.
"words": The first letter of each word defaults to a capital letter; all other letters default to lowercase.
"characters": All letters default to uppercase.

undefined

autocomplete / autoComplete

AutoComplete | undefined

Provides a hint for a user agent's autocomplete feature. See the HTML autocomplete attribute for a complete list of values and details on how to use autoComplete.

undefined

autofocus / autoFocus

boolean | undefined

Specify whether the input should have focus when the page loads.

undefined

disabled

boolean | undefined

Prevents the input from being interacted with: it cannot be pressed or focused.

undefined

enterkeyhint

What action label (or icon) to present for the enter key on virtual keyboards. Possible values:

"done": Typically meaning there is nothing more to input and the input method editor (IME) will be closed.
"enter": Typically inserting a new line.
"go": Typically meaning to take the user to the target of the text they typed.
"next": Typically taking the user to the next field that will accept text.
"previous": Typically taking the user to the previous field that will accept text.
"search": Typically taking the user to the results of searching for the text they have typed.
"send": Typically delivering the text to its target.

undefined

form

HTMLFormElement | null | string

The <form> element to associate the input with (its form owner).

The value of this attribute must be the id of a <form> in the same document. If this attribute is not set, the <qds-input> is associated with its ancestor <form> element, if any.

This attribute lets you associate <qds-input> elements to <form>s anywhere in the document, not just inside a <form>. It can also override an ancestor <form> element.

null

inputmode

Provide a hint to browsers as to the type of virtual keyboard configuration to use when editing this element or its contents.

undefined

NodeListOf<HTMLLabelElement> | null

Returns a list of the <label> elements associated with the qds-input element.

null

max

number | string | undefined

Defines the greatest value in the range of permitted values. If the value entered into the input exceeds this, the input fails constraint validation. Only valid for date, datetime-local, month, time, and week inputs.

If this value isn't a valid number, then the input has no maximum value.

undefined

maxlength / maxLength

number | undefined

The maximum number of characters (as UTF-16 code units) the user can enter into the input. This must be an non-negative integer value. If no maxlength is specified, or an invalid value is specified, the input has no maximum length. Only valid for email, password, search, tel, text, and url inputs.

The input will fail constraint validation if the length of the text entered into the field is greater than maxlength UTF-16 code units long. By default, browsers prevent users from entering more characters than allowed by the maxlength attribute. See Client-side validation for more information.

undefined

min

number | string | undefined

Defines the most negative value in the range of permitted values. If the value entered into the input is less than this, the input fails constraint validation. Only valid for date, datetime-local, month, time, and week inputs.

This value must be less than or equal to the value of the max attribute. If this value isn't a valid number, then the input has no minimum value.

undefined

minlength / minLength

number | undefined

The minimum number of characters (as UTF-16 code units) the user can enter into the input. This must be an non-negative integer value smaller than or equal to the value specified by maxlength. If no minlength is specified, or an invalid value is specified, the input has no minimum length. Only valid for email, password, search, tel, text, and url inputs.

The input will fail constraint validation if the length of the text entered into the field is fewer than minlength UTF-16 code units long, preventing form submission. See Client-side validation for more information.

undefined

multiple

boolean | undefined

Specifies if multiple comma-separated email addresses can be entered. Only valid for email inputs.

undefined

name

string | undefined

The name of the input, which is submitted with the form data.

undefined

no-icon / noIcon

boolean | undefined

Hide the input type's icon.

NOTE: Due to browser limitations, the icon may not be hidden in all browsers.

false

pattern

string | undefined

Defines a regular expression that the input's value must match in order for the value to pass constraint validation. It must be a valid JavaScript regular expression, as used by the RegExp type, and as documented in MDN's guide on regular expressions; the 'u' flag is specified when compiling the regular expression, so that the pattern is treated as a sequence of Unicode code points, instead of as ASCII. No forward slashes should be specified around the pattern text. Only valid for email, password, search, tel, text, and url inputs.

If the pattern is invalid, no regular expression is applied and this property is ignored. If the pattern is valid and a non-empty value does not match the pattern, constraint validation will prevent form submission.

undefined

placeholder

string | undefined

Text that appears in the input when it has no value set. Only valid for email, number, password, search, tel, text, and url inputs.

undefined

required

boolean | undefined

A value must be specified for the input before the owning form can be submitted. Not valid for color inputs.

See Client-side validation and the HTML attribute: required for more information.

undefined

selection-direction / selectionDirection

"backward" | "forward" | "none" | null

Get or set the selection direction of a text selection.

NOTE: This property has no effect when used as an attribute.

null

selection-end / selectionEnd

null | number

Get or set the ending position or offset of a text selection.

NOTE: This property has no effect when used as an attribute.

null

selection-start / selectionStart

null | number

Get or set the starting position or offset of a text selection.

NOTE: This property has no effect when used as an attribute.

null

size

"large" | "small" | "standard" | undefined

The input's size.

NOTE: The native size HTML attribute is not supported. CSS width should be used instead if this functionality is needed.

'standard'

spellcheck / spellCheck

boolean | undefined

Defines whether the input may be checked for spelling errors.

undefined

step

"any" | number | undefined

Specifies the granularity that the value must adhere to. Only valid for date, datetime-local, month, number, time, and week inputs.

The value must be a positive number—integer or float—or the special value any, which means no stepping is implied, and any value is allowed (barring other constraints, such as min and max).

If any is not explicitly set, valid values for the number are the basis for stepping — the min value and increments of the step value, up to the max value, if specified.

undefined

type

"color" | "date" | "datetime-local" | "email" | "month" | "number" | "password" | "search" | "tel" | "text" | "time" | "url" | "week" | undefined

The type of input to render:

"date": An input for entering a date (year, month, and day, with no time). Opens a date picker or numeric wheels for year, month, day when active in supporting browsers.
"datetime-local": An input for entering a date and time, with no time zone. Opens a date picker or numeric wheels for date and time components when active in supporting browsers.
"email": An input for editing an email address. Looks like a "text" input, but has validation parameters and relevant keyboard in supporting browsers and devices with dynamic keyboards.
"month": An input for entering a month and year, with no time zone.
"number": An input for entering a number. Displays a spinner and adds default validation when supported. Displays a numeric keypad in some devices with dynamic keypads.
"password": A single-line text input whose value is obscured. Will alert user if site is not secure.
"search": A single-line text input for entering search strings. Line-breaks are automatically removed from the input value. May include a delete icon in supporting browsers that can be used to clear the input. Displays a search icon instead of enter key on some devices with dynamic keypads.
"tel": An input for entering a telephone number. Displays a telephone keypad in some devices with dynamic keypads.
"text": A single-line text input. Line-breaks are automatically removed from the input value.
"time": An input for entering a time value with no time zone.
"url": An input for entering a URL. Looks like a "text" input, but has validation parameters and relevant keyboard in supporting browsers and devices with dynamic keyboards.
"week": An input for entering a date consisting of a week-year number and a week number with no time zone.

undefined

validation-message / validationMessage

string

The error message that would be shown to the user if the <qds-select> was to be checked for validity.

''

ValidityState

The ValidityState object for this <qds-select>.

VALID_STATE

value

null | number | string | undefined

The value of the input.

undefined

will-validate / willValidate

boolean

True if <qds-input> will be validated when the form is submitted; false otherwise.

false

Events

Event

Type

Description

Bubbles

Cancelable

Composed

qdsBlur

{ readonly relatedTarget: EventTarget | null; }

Emitted when the input loses focus.

qdsChange

void

Emitted when an alteration to the input's value is committed by the user.

qdsFocus

{ readonly relatedTarget: EventTarget | null; }

Emitted when the input gains focus.

qdsInput

{ readonly data: string | null; readonly inputType: string; readonly isComposing: boolean; }

Emitted when the input's value changes.

Types​

Text​

Number​

Date and time​

Email​

Password​

Search​

Telephone​

URL​

Color​

Size​

NoIcon​

Layout​

In forms​

Additional options​

Spellchecking​

Required​

Placeholder​

Disabled​

Implementation tips​

Custom width​

Custom format​

Importing​

Accessibility​

Component reference​

Properties​

Events​

Types

Text

Number

Date and time

Email

Password

Search

Telephone

URL

Color

Size

NoIcon

Layout

In forms

Additional options

Spellchecking

Required

Placeholder

Disabled

Implementation tips

Custom width

Custom format

Importing

Accessibility

Component reference

Properties

Events