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>

Help Text Jump to heading

Add descriptive help text to an input with the help-text attribute. For help texts that contain HTML, use the help-text slot instead.

<wa-input label="Nickname" help-text="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 clearable attribute to add a clear button when the input has content.

<wa-input placeholder="Clearable" clearable></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>

Filled Inputs Jump to heading

Add the filled attribute to draw a filled input.

<wa-input placeholder="Type something" filled></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>

Prefix & Suffix Icons Jump to heading

Use the prefix and suffix slots to add icons.

<wa-input placeholder="Small" size="small">
  <wa-icon name="house" variant="solid" slot="prefix"></wa-icon>
  <wa-icon name="comment" variant="solid" slot="suffix"></wa-icon>
</wa-input>
<br />
<wa-input placeholder="Medium" size="medium">
  <wa-icon name="house" variant="solid" slot="prefix"></wa-icon>
  <wa-icon name="comment" variant="solid" slot="suffix"></wa-icon>
</wa-input>
<br />
<wa-input placeholder="Large" size="large">
  <wa-icon name="house" variant="solid" slot="prefix"></wa-icon>
  <wa-icon name="comment" variant="solid" slot="suffix"></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.

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

<style>
  .label-on-left {
    --label-width: 3.75rem;
    --gap-width: 1rem;
  }

  .label-on-left + .label-on-left {
    margin-top: var(--wa-space-m);
  }

  .label-on-left::part(form-control) {
    display: grid;
    grid: auto / var(--label-width) 1fr;
    gap: var(--wa-space-3xs) var(--gap-width);
    align-items: center;
  }

  .label-on-left::part(form-control-label) {
    text-align: right;
  }

  .label-on-left::part(form-control-help-text) {
    grid-column-start: 2;
  }
</style>

Slots Jump to heading

Name	Description
`label`	The input's label. Alternatively, you can use the `label` attribute.
`prefix`	Used to prepend a presentational icon or similar element to the input.
`suffix`	Used to append a presentational icon or similar element to the input.
`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.
`help-text`	Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.

Properties Jump to heading

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 `null \| string`
`size` `size`	The input's size. Type `'small' \| 'medium' \| 'large'` Default `'medium'`
`filled` `filled`	Draws a filled input. Type `boolean` Default `false`
`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 `''`
`helpText` `help-text`	The input's help text. If you need to display HTML, use the `help-text` slot instead. Type `string` Default `''`
`clearable` `clearable`	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`
`noSpinButtons` `no-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`
`withHelpText` `with-help-text`	Used for SSR. Will determine if the SSRed component will have the help text slot rendered on initial paint. Type `boolean` Default `false`

Methods Jump to heading

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

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

CSS custom properties Jump to heading

Name	Description
`--background-color`	The input's background color.
`--border-color`	The color of the input's borders.
`--border-radius`	The radius of the input's corners.
`--border-style`	The style of the input's borders.
`--border-width`	The width of the input's borders. Expects a single value.
`--box-shadow`	The shadow effects around the edges of the input.

CSS parts Jump to heading

Name	Description
`form-control`	The form control that wraps the label, input, and help text.
`form-control-label`	The label's wrapper.
`form-control-input`	The input's wrapper.
`form-control-help-text`	The help text's wrapper.
`base`	The component's base wrapper.
`input`	The internal `<input>` control.
`prefix`	The container that wraps the prefix.
`clear-button`	The clear button.
`password-toggle-button`	The password toggle button.
`suffix`	The container that wraps the suffix.

Dependencies Jump to heading

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

<wa-icon>

Importing Jump to heading

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

CDN

npm

React

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

import 'https://early.webawesome.com/webawesome@3.0.0-alpha.4/dist/components/input/input.js';

Coming soon!

Input

Examples Jump to heading #

Labels Jump to heading #

Help Text Jump to heading #

Placeholders Jump to heading #

Clearable Jump to heading #

Toggle Password Jump to heading #

Filled Inputs Jump to heading #

Disabled Jump to heading #

Sizes Jump to heading #

Pill Jump to heading #

Input Types Jump to heading #

Prefix & Suffix Icons Jump to heading #

Customizing Label Position Jump to heading #

Slots Jump to heading #

Properties Jump to heading #

Methods Jump to heading #

Events Jump to heading #

CSS custom properties Jump to heading #

CSS parts Jump to heading #

Dependencies Jump to heading #

Importing Jump to heading #

Examples Jump to heading

Labels Jump to heading

Help Text Jump to heading

Placeholders Jump to heading

Clearable Jump to heading

Toggle Password Jump to heading

Filled Inputs Jump to heading

Disabled Jump to heading

Sizes Jump to heading

Pill Jump to heading

Input Types Jump to heading

Prefix & Suffix Icons Jump to heading

Customizing Label Position Jump to heading

Slots Jump to heading

Properties Jump to heading

Methods Jump to heading

Events Jump to heading

CSS custom properties Jump to heading

CSS parts Jump to heading

Dependencies Jump to heading

Importing Jump to heading