Input

<wa-input>

Since 2.0

stable

Inputs collect data from the user.

<wa-input></wa-input>

This component works with standard <form> elements. Please refer to the section on form controls to learn more about form submission and client-side validation.

Examples Jump to heading

Labels Jump to heading

Use the label attribute to give the input an accessible label. For labels that contain HTML, use the label slot instead.

<wa-input label="What is your name?"></wa-input>

Hint Jump to heading

Add descriptive hint to an input with the hint attribute. For hints that contain HTML, use the hint slot instead.

<wa-input label="Nickname" hint="What would you like people to call you?"></wa-input>

Placeholders Jump to heading

Use the placeholder attribute to add a placeholder.

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

Clearable Jump to heading

Add the with-clear attribute to add a clear button when the input has content.

<wa-input placeholder="Clearable" with-clear></wa-input>

Toggle Password Jump to heading

Add the password-toggle attribute to add a toggle button that will show the password when activated.

<wa-input type="password" placeholder="Password Toggle" password-toggle></wa-input>

Appearance Jump to heading

Use the appearance attribute to change the input's visual appearance.

<wa-input placeholder="Type something" appearance="filled"></wa-input><br />
<wa-input placeholder="Type something" appearance="filled-outlined"></wa-input><br />
<wa-input placeholder="Type something" appearance="outlined"></wa-input>

Disabled Jump to heading

Use the disabled attribute to disable an input.

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

Sizes Jump to heading

Use the size attribute to change an input's size.

<wa-input placeholder="Small" size="small"></wa-input>
<br />
<wa-input placeholder="Medium" size="medium"></wa-input>
<br />
<wa-input placeholder="Large" size="large"></wa-input>

Pill Jump to heading

Use the pill attribute to give inputs rounded edges.

<wa-input placeholder="Small" size="small" pill></wa-input>
<br />
<wa-input placeholder="Medium" size="medium" pill></wa-input>
<br />
<wa-input placeholder="Large" size="large" pill></wa-input>

Input Types Jump to heading

The type attribute controls the type of input the browser renders.

<wa-input type="email" placeholder="Email"></wa-input>
<br />
<wa-input type="number" placeholder="Number"></wa-input>
<br />
<wa-input type="date" placeholder="Date"></wa-input>

Start & End Decorations Jump to heading

Use the start and end slots to add presentational elements like <wa-icon> within the input.

<wa-input placeholder="Small" size="small">
  <wa-icon name="house" slot="start"></wa-icon>
  <wa-icon name="comment" slot="end"></wa-icon>
</wa-input>
<br />
<wa-input placeholder="Medium" size="medium">
  <wa-icon name="house" slot="start"></wa-icon>
  <wa-icon name="comment" slot="end"></wa-icon>
</wa-input>
<br />
<wa-input placeholder="Large" size="large">
  <wa-icon name="house" slot="start"></wa-icon>
  <wa-icon name="comment" slot="end"></wa-icon>
</wa-input>

Customizing Label Position Jump to heading

Use CSS parts to customize the way form controls are drawn. This example uses CSS grid to position the label to the left of the control, but the possible orientations are nearly endless. The same technique works for inputs, textareas, radio groups, and similar form controls.

<div class="label-on-left">
  <wa-input label="Name" hint="Enter your name"></wa-input>
  <wa-input label="Email" type="email" hint="Enter your email"></wa-input>
  <wa-textarea label="Bio" hint="Tell us something about yourself"></wa-textarea>
</div>

<style>
  .label-on-left {
    display: grid;
    grid-template-columns: auto 1fr;
    gap: var(--wa-space-l);
    align-items: center;

    wa-input,
    wa-textarea {
      grid-column: 1 / -1;
      grid-row-end: span 2;
      display: grid;
      grid-template-columns: subgrid;
      gap: 0 var(--wa-space-l);
      align-items: center;
    }

    ::part(label) {
      text-align: right;
    }

    ::part(hint) {
      grid-column: 2;
    }
  }
</style>

Slots Jump to heading

Learn more about using slots.

Name	Description
`label`	The input's label. Alternatively, you can use the `label` attribute.
`start`	An element, such as `<wa-icon>`, placed at the start of the input control.
`end`	An element, such as `<wa-icon>`, placed at the end of the input control.
`clear-icon`	An icon to use in lieu of the default clear icon.
`show-password-icon`	An icon to use in lieu of the default show password icon.
`hide-password-icon`	An icon to use in lieu of the default hide password icon.
`hint`	Text that describes how to use the input. Alternatively, you can use the `hint` attribute.

Attributes & Properties Jump to heading

Learn more about attributes and properties.

Name	Description	Reflects
`type` `type`	The type of input. Works the same as a native `<input>` element, but only a subset of types are supported. Defaults to `text`. Type `'date' \| 'datetime-local' \| 'email' \| 'number' \| 'password' \| 'search' \| 'tel' \| 'text' \| 'time' \| 'url'` Default `'text'`
`value`	The current value of the input, submitted as a name/value pair with form data.
`defaultValue` `value`	The default value of the form control. Primarily used for resetting the form control. Type `string \| null`
`size` `size`	The input's size. Type `'small' \| 'medium' \| 'large'` Default `'medium'`
`appearance` `appearance`	The input's visual appearance. Type `'filled' \| 'outlined' \| 'filled-outlined'` Default `'outlined'`
`pill` `pill`	Draws a pill-style input with rounded edges. Type `boolean` Default `false`
`label` `label`	The input's label. If you need to display HTML, use the `label` slot instead. Type `string` Default `''`
`hint` `hint`	The input's hint. If you need to display HTML, use the `hint` slot instead. Type `string` Default `''`
`withClear` `with-clear`	Adds a clear button when the input is not empty. Type `boolean` Default `false`
`placeholder` `placeholder`	Placeholder text to show as a hint when the input is empty. Type `string` Default `''`
`readonly` `readonly`	Makes the input readonly. Type `boolean` Default `false`
`passwordToggle` `password-toggle`	Adds a button to toggle the password's visibility. Only applies to password types. Type `boolean` Default `false`
`passwordVisible` `password-visible`	Determines whether or not the password is currently visible. Only applies to password input types. Type `boolean` Default `false`
`withoutSpinButtons` `without-spin-buttons`	Hides the browser's built-in increment/decrement spin buttons for number inputs. Type `boolean` Default `false`
`form` `form`	By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you to place the form control outside of a form and associate it with the form that has this `id`. The form must be in the same document or shadow root for this to work. Type `null` Default `null`
`required` `required`	Makes the input a required field. Type `boolean` Default `false`
`pattern` `pattern`	A regular expression pattern to validate input against. Type `string`
`minlength` `minlength`	The minimum length of input that will be considered valid. Type `number`
`maxlength` `maxlength`	The maximum length of input that will be considered valid. Type `number`
`min` `min`	The input's minimum value. Only applies to date and number input types. Type `number \| string`
`max` `max`	The input's maximum value. Only applies to date and number input types. Type `number \| string`
`step` `step`	Specifies the granularity that the value must adhere to, or the special value `any` which means no stepping is implied, allowing any numeric value. Only applies to date and number input types. Type `number \| 'any'`
`autocapitalize` `autocapitalize`	Controls whether and how text input is automatically capitalized as it is entered by the user. Type `'off' \| 'none' \| 'on' \| 'sentences' \| 'words' \| 'characters'`
`autocorrect` `autocorrect`	Indicates whether the browser's autocorrect feature is on or off. Type `'off' \| 'on'`
`autocomplete` `autocomplete`	Specifies what permission the browser has to provide assistance in filling out form field values. Refer to this page on MDN for available values. Type `string`
`autofocus` `autofocus`	Indicates that the input should receive focus on page load. Type `boolean`
`enterkeyhint` `enterkeyhint`	Used to customize the label or icon of the Enter key on virtual keyboards. Type `'enter' \| 'done' \| 'go' \| 'next' \| 'previous' \| 'search' \| 'send'`
`spellcheck` `spellcheck`	Enables spell checking on the input. Type `boolean` Default `true`
`inputmode` `inputmode`	Tells the browser what type of data will be entered by the user, allowing it to display the appropriate virtual keyboard on supportive devices. Type `'none' \| 'text' \| 'decimal' \| 'numeric' \| 'tel' \| 'search' \| 'email' \| 'url'`
`withLabel` `with-label`	Used for SSR. Will determine if the SSRed component will have the label slot rendered on initial paint. Type `boolean` Default `false`
`withHint` `with-hint`	Used for SSR. Will determine if the SSRed component will have the hint slot rendered on initial paint. Type `boolean` Default `false`

Methods Jump to heading

Learn more about methods.

Name	Description	Arguments
`focus()`	Sets focus on the input.	`options: FocusOptions`
`blur()`	Removes focus from the input.
`select()`	Selects all the text in the input.
`setSelectionRange()`	Sets the start and end positions of the text selection (0-based).	`selectionStart: number, selectionEnd: number, selectionDirection: 'forward' \| 'backward' \| 'none'`
`setRangeText()`	Replaces a range of text with a new string.	`replacement: string, start: number, end: number, selectMode: 'select' \| 'start' \| 'end' \| 'preserve'`
`showPicker()`	Displays the browser picker for an input element (only works if the browser supports it for the input type).
`stepUp()`	Increments the value of a numeric input type by the value of the step attribute.
`stepDown()`	Decrements the value of a numeric input type by the value of the step attribute.

Events Jump to heading

Learn more about events.

Name	Description
`input`	Emitted when the control receives input.
`change`	Emitted when an alteration to the control's value is committed by the user.
`blur`	Emitted when the control loses focus.
`focus`	Emitted when the control gains focus.
`wa-clear`	Emitted when the clear button is activated.
`wa-invalid`	Emitted when the form control has been checked for validity and its constraints aren't satisfied.

Custom States Jump to heading

Learn more about custom states.

Name	Description	CSS selector
`blank`	The input is empty.	`:state(blank)`

CSS parts Jump to heading

Learn more about CSS parts.

Name	Description	CSS selector
`label`	The label	`::part(label)`
`hint`	The hint's wrapper.	`::part(hint)`
`base`	The wrapper being rendered as an input	`::part(base)`
`input`	The internal `<input>` control.	`::part(input)`
`start`	The container that wraps the `start` slot.	`::part(start)`
`clear-button`	The clear button.	`::part(clear-button)`
`password-toggle-button`	The password toggle button.	`::part(password-toggle-button)`
`end`	The container that wraps the `end` slot.	`::part(end)`

Dependencies Jump to heading

This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.

<wa-icon>

Importing Jump to heading

Autoloading components via projects is the recommended way to import components. If you prefer to do it manually, use one of the following code snippets.

CDN

npm

React

Let your project code do the work! Sign up for free to use a project with your very own CDN — it's the fastest and easiest way to use Web Awesome.

To manually import this component from NPM, use the following code.

import '@awesome.me/webawesome/dist/components/input/input.js';

To manually import this component from React, use the following code.

import WaInput from '@awesome.me/webawesome/dist/react/input';

Need a hand?

Report a bug

Ask for help

Getting Started

Resources

Components

Style Utilities

Layout

Patterns

Theming

Design Tokens

Terms & Policies

Web Awesome

Input

Examples Jump to heading

Labels Jump to heading

Hint Jump to heading

Placeholders Jump to heading

Clearable Jump to heading

Toggle Password Jump to heading

Appearance Jump to heading

Disabled Jump to heading

Sizes Jump to heading

Pill Jump to heading

Input Types Jump to heading

Start & End Decorations Jump to heading

Customizing Label Position Jump to heading

Slots Jump to heading

Attributes & Properties Jump to heading

Methods Jump to heading

Events Jump to heading

Custom States Jump to heading

CSS parts Jump to heading

Dependencies Jump to heading

Importing Jump to heading

Get a lifetime discount on Web Awesome Pro!

Getting Started

Resources

Components

Style Utilities

Layout

Patterns

Theming

Design Tokens

Terms & Policies

Web Awesome

Web Awesome Elsewhere

Input

Examples Jump to heading

Labels Jump to heading

Hint Jump to heading

Placeholders Jump to heading

Clearable Jump to heading

Toggle Password Jump to heading

Appearance Jump to heading

Disabled Jump to heading

Sizes Jump to heading

Pill Jump to heading

Input Types Jump to heading

Start & End Decorations Jump to heading

Customizing Label Position Jump to heading

Slots Jump to heading

Attributes & Properties Jump to heading

Methods Jump to heading

Events Jump to heading

Custom States Jump to heading

CSS parts Jump to heading

Dependencies Jump to heading

Importing Jump to heading

Get a lifetime discount on Web Awesome Pro!