Skip to content

Text Field

<quiet-text-field> stable since 1.0

Text fields let users input and edit text.

<quiet-text-field name="name" label="Name"></quiet-text-field>

Examples

Labels and descriptions

You can use the label and description attributes to provide plain text labels and descriptions for the text field. If you want to provide HTML, use the label and description slots instead.

For more information, visit our website. 
<quiet-text-field name="name" label="Name">
  <span slot="description">
    For more information, <a href="https://example.com/" target="_blank">visit our website</a>.
  </span>
</quiet-text-field>

Providing an initial value

Use the value attribute to provide an initial value for the text field.

<quiet-text-field name="name" label="Name" value="Meowy McGee"></quiet-text-field>

Changing the type

Text fields support more than just text. Use the type attribute to change the type of input they accept. 





<quiet-text-field type="color" label="Color" value="#787acf"></quiet-text-field><br>
<quiet-text-field type="date" label="Date" value="1989-03-12"></quiet-text-field><br>
<quiet-text-field type="time" label="Time" value="12:00:00"></quiet-text-field><br>
<quiet-text-field type="number" label="Number" value="42" inputmode="numeric"></quiet-text-field><br>
<quiet-text-field type="password" label="Password" value="hunter2"></quiet-text-field>

Adding a placeholder

Use the placeholder attribute to show a placeholder in the text field when it's empty.

<quiet-text-field 
  type="email"
  label="Email"
  placeholder="you@example.com"
></quiet-text-field>

Adding a clear button

To add a clear button to the text field, use the clearable attribute. The quiet-input event will be emitted when the clear button is activated. 

<quiet-text-field 
  name="name" 
  label="Name" 
  value="Meowy McGee"
  clearable
></quiet-text-field>

Start and end content

Use the start and end slots to add presentational icons or text. Avoid interactive elements such as buttons, links, etc. Works well with <quiet-icon> and <svg> elements.



https:// 
<quiet-text-field name="search" label="Search">
  <quiet-icon slot="start" name="search"></quiet-icon>
</quiet-text-field>

<br>

<quiet-text-field type="email" name="email" label="Email">
  <quiet-icon slot="end" name="mail"></quiet-icon>
</quiet-text-field>

<br>

<quiet-text-field type="url" name="url" label="URL">
  <span slot="start">https://</span>
</quiet-text-field>

Filled and unstyled text fields

Set the appearance attribute to normal, filled, or unstyled to change the text field's appearance. 



<quiet-text-field appearance="normal" label="Normal text field" placeholder="Enter some text"></quiet-text-field><br>
<quiet-text-field appearance="filled" label="Filled text field" placeholder="Enter some text"></quiet-text-field><br>
<quiet-text-field appearance="unstyled" label="Unstyled text field" placeholder="Enter some text"></quiet-text-field>

Pill-shaped text fields

Text fields can be rendered with pill-shaped edges by adding the pill attribute.

<quiet-text-field pill label="Pill-shaped"></quiet-text-field>

Changing the size

Use the size attribute to change the text field's size.





<quiet-text-field size="xs" label="Extra small"></quiet-text-field><br>
<quiet-text-field size="sm" label="Small"></quiet-text-field><br>
<quiet-text-field size="md" label="Medium"></quiet-text-field><br>
<quiet-text-field size="lg" label="Large"></quiet-text-field><br>
<quiet-text-field size="xl" label="Extra large"></quiet-text-field>

Disabling

Use the disabled attribute to disable the text field.

<quiet-text-field label="Disabled" disabled></quiet-text-field>

Showing labels on the side

With a bit of custom CSS, you can show labels on the side instead of on top of the text field.



<div class="text-field__side-labels">
  <quiet-text-field name="name" label="Name" description="What do people call you?"></quiet-text-field>
  <br>
  <quiet-text-field type="email" name="email" label="Email" description="How can we get in touch?"></quiet-text-field>
</div>

<style>
  .text-field__side-labels {
    quiet-text-field {
      --label-width: 4.5rem; /* Change this to make more room for the label */

      display: grid;
      grid: auto / var(--label-width) 1fr;
      gap: .25em;
      align-items: center;    
    }

    quiet-text-field::part(label) {
      text-align: end;
    }

    quiet-text-field::part(description) {
      grid-column-start: 2;
      order: 3;
      margin-block: 0;
    }
  }
</style>

Validation

A number of attributes can be used to enable validation using the Constraint Validation API . These include required, pattern, minlength, maxlength, min, max, and step. They work exactly like their native counterparts.





Submit Reset 
<form action="about:blank" method="get" target="_blank">
  <quiet-text-field name="required" label="Required" required></quiet-text-field><br>
  <quiet-text-field name="minlength" label="Minimum length (enter at least five characters)" required minlength="5"></quiet-text-field><br>
  <quiet-text-field name="maxlength" label="Maximum length (enter no more than five characters)" required maxlength="5"></quiet-text-field><br>
  <quiet-text-field name="pattern" label="Pattern (enter three to five letters)" required pattern="[A-Za-z]{3,5}"></quiet-text-field><br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

Using custom validation

Use the custom-validity attribute to make the text field invalid and show a custom error message on submit. This will override all other validation parameters. To clear the error, remove the attribute or set it to an empty string.


Submit 
<form action="about:blank" method="get" target="_blank">
  <quiet-text-field 
    name="name"
    label="Name"
    description="This field will be invalid until the custom-validity attribute is removed"
    custom-validity="Not so fast, bubba!"
  ></quiet-text-field>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
</form>

Most validation attributes work exactly like their native counterparts. However, the custom-validity attribute is offered in lieu of the setCustomValidity() method. This allows you to declaratively set custom errors instead of having to call a method with JavaScript.

Styling validation

You can style valid and invalid text fields using the :valid and :invalid pseudo classes.


Submit Reset 
<form action="about:blank" method="get" target="_blank" class="text-field__validation-pseudo">
  <quiet-text-field 
    name="name"
    label="Name"
    description="This field is required"
    required
  ></quiet-text-field>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .text-field__validation-pseudo {
    quiet-text-field:valid {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-text-field:invalid {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

However, these selectors will match even before the user has had a chance to fill out the form. More often than not, you'll want to use the user-valid and user-invalid custom states instead. This way, validation styles are only shown after the user interacts with the form control or when the form is submitted.


Submit Reset 
<form action="about:blank" method="get" target="_blank" class="text-field__validation-custom">
  <quiet-text-field 
    name="name"
    label="Name"
    description="This field is required"
    required
  ></quiet-text-field>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .text-field__validation-custom {
    quiet-text-field:state(user-valid) {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-text-field:state(user-invalid) {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

API

Importing

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN npm

To manually import <quiet-text-field> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet@1.0.0/dist/components/text-field/text-field.js';

To manually import <quiet-text-field> from npm, use the following code.

import '@quietui/quiet/dist/components/text-field/text-field.js';

Slots

Text Field supports the following slots. Learn more about using slots

Name Description
label The text field's label. For plain-text labels, you can use the label attribute instead.
description The text field's description. For plain-text descriptions, you can use the description attribute instead.
start An icon or similar element to place before the label. Works great with <quiet-icon>.
end An icon or similar element to place after the label. Works great with <quiet-icon>.

Properties

Text Field has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute Description Reflects Type Default
associatedForm A reference to the <form> associated with the form control, or null if no form is associated. HTMLFormElement
null 		null
label The text field's label. If you need to provide HTML in the label, use the label slot instead. string
description The text field's description. If you need to provide HTML in the description, use the description slot instead. string
name The name of the text field. This will be submitted with the form as a name/value pair. string
value The text field's value. string ''
placeholder A placeholder to show in the text field when it's blank. string
disabled Disables the text field. boolean false
readonly Makes the text field a read-only field. boolean false
clearable Adds a clear button to the text field when it's not blank. boolean false
appearance The type of text field to render. 'normal'
'filled'
'unstyled' 		'normal'
size The text field's size. 'xs'
'sm'
'md'
'lg'
'xl' 		'md'
pill Draws the text field in a pill shape. boolean false
type The type of data the text field will accept. 'color'
'date'
'datetime-local'
'email'
'month'
'number'
'password'
'search'
'tel'
'text'
'time'
'url'
'week' 		'text'
form The form to associate this control with. If omitted, the closest containing <form> will be used. The value of this attribute must be an ID of a form in the same document or shadow root. string
required Makes the text field required. Form submission will not be allowed when this is set and the text field is blank. boolean false
pattern A regular expression the value should match to be considered valid. string
minLength
minlength 		The minimum string length that will be considered valid. number
maxLength
maxlength 		The maximum string length that will be considered valid. number
min The minimum value for date/time types. number
max The maximum value for date/time types. number
step The granularity the value must adhere to when incrementing and decrementing. number
'any'
customValidity
custom-validity 		You can provide a custom error message to force the text field to be invalid. To clear the error, set this to an empty string. string ''
autocapitalize Turns autocapitalize on or off in supported browsers. 'off'
'none'
'on'
'sentences'
'words'
'characters'
autocomplete Tells the browser how to autocomplete the text field. See this page for available values. string
autocorrect Turns autocorrect on or off in supported browsers. 'off'
'on'
autofocus Tells the browser to focus the text field when the page loads or a dialog is shown. boolean
enterkeyhint Sets the enter key label on virtual keyboards. 'enter'
'done'
'go'
'next'
'previous'
'search'
'send'
inputmode Provides the browser with a hint about the type of data that might be entered by the user, allowing the appropriate virtual keyboard to be displayed on supported devices. 'none'
'text'
'decimal'
'numeric'
'tel'
'search'
'email'
'url'
spellcheck Turns spell checking on or off in supported browsers. boolean

Methods

Text Field supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods

Name Description Arguments
focus() Sets focus to the text field.
blur() Removes focus from the text field.
checkValidity() Checks if the form control has any restraints and whether it satisfies them. If invalid, false will be returned and the invalid event will be dispatched. If valid, true will be returned.
reportValidity() Checks if the form control has any restraints and whether it satisfies them. If invalid, false will be returned and the invalid event will be dispatched. In addition, the problem will be reported to the user. If valid, true will be returned.
select() Selects all text in the text field.
setSelectionRange() Sets the start and end positions of the current text selection in the text field. start: number, end: number, direction: 'forward' <br> 'backward' <br> 'none'
setRangeText() Replaces a range of text in the text field with a new string. replacement: string, start: number, end: number, selectMode: 'select' <br> 'start' <br> 'end' <br> 'preserve'
showPicker() For types that support a picker, such as color and date selectors, this will cause the picker to show.
stepDown() When a supported type is used, this method will decrease the text field's value by step. This is a programmatic change, so input and change events will not be emitted when this is called.
stepUp() When a supported type is used, this method will increase the text field's value by step. This is a programmatic change, so input and change events will not be emitted when this is called.

Events

Text Field dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name Description
input
quiet-blur Emitted when the text field loses focus. This event does not bubble.
quiet-change Emitted when the user commits changes to the text field's value.
quiet-focus Emitted when the text field receives focus. This event does not bubble.
quiet-input Emitted when the text field receives input.

CSS parts

Text Field exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name Description CSS selector
label The element that contains the text field's label. ::part(label)
description The element that contains the text field's description. ::part(description)
visual-box The element that wraps the internal text box. ::part(visual-box)
text-box The internal text box, an <input> element. ::part(text-box)
clear-button The clear button, a <button> element. ::part(clear-button)
password-toggle-button The password toggle button, a <button> element. ::part(password-toggle-button)

Custom States

Text Field has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name Description CSS selector
disabled Applied when the text field is disabled. :state(disabled)
blank Applied when the text field has a blank value. :state(blank)
focused Applied when the text field has focus. :state(focused)
user-valid Applied when the text field is valid and the user has sufficiently interacted with it. :state(user-valid)
user-invalid Applied when the text field is invalid and the user has sufficiently interacted with it. :state(user-invalid)

Dependencies

Text Field automatically imports the following elements. Sub-dependencies are also included in this list.

Search this website Toggle dark mode Get the code on GitHub Follow @quietui.org on Bluesky Follow @quiet_ui on X
    No results found