Text field - Elements

A text field is a single-line input component used for entering and editing textual data.

AndroidreleasedElementsreleasediOSreleasedReactreleasedVuereleased

Example theme:

Accessibility

If a visible label isn't specified, an aria-label must be provided to the text field for accessibility. If the field is labeled by a separate element, an aria-labelledby property must be provided using the id of the labeling element instead.

Always provide a visible label (do not rely on placeholder alone).
Do not rely on color alone for interaction feedback (e.g. error states).
Interaction patterns should follow platform-native expectations (e.g. tap zones, keyboard navigation, etc) and must not block accessibility tools.

When used with an affix

When search or clear set on the affix component it renders a button and a default aria-label. If the aria-label incorrect for your context, you may provide your own describing the action.

html

<w-affix search aria-label="Ad Search"></w-affix>
<w-affix clear aria-label="Clear text input"></w-affix>

Usage

html

<w-textfield label="Email" type="email"></w-textfield>

Validation

Set the invalid attribute to display a textfield as invalid.

invalid should be paired with help-text to provide feedback to the user about how to correct the error.

html

<w-textfield 
    label="Email"
    invalid
    help-text="An email should have an @ sign and a domain name, for example ola.nordmann@finn.no"
></w-textfield>

Examples

Placeholder

Placeholder text can be used to describe the expected value or formatting for the textfield.

Placeholder text will only appear when the textfield is empty, and must not be used as a substitute for labeling the element with a visible label.

html

<w-textfield label="Email" placeholder="ola.nordmann@finn.no"></w-textfield>

Prefix label

html

<w-textfield label="Price">
  <w-affix slot="prefix" label="kr"></w-affix>
</w-textfield>

Suffix Label

html

<w-textfield label="Price">
  <w-affix slot="suffix" label="kr"></w-affix>
</w-textfield>

Prefix Search Icon

html

<w-textfield label="Search">
  <w-affix slot="prefix" search></w-affix>
</w-textfield>

Suffix Search Icon

If you wrap the textfield with affix in a form element, clicking the search button will automatically submit the form

html

<form>
  <w-textfield label="Search">
    <w-affix slot="prefix" search></w-affix>
  </w-textfield>
</form>

Suffix Clear Icon

Clicking the clear button will reset the textfield

html

<w-textfield label="Search input">
  <w-affix slot="suffix" clear></w-affix>
</w-textfield>

Affix with arbitrary icon

html

<w-textfield label="Award">
  <w-affix slot="prefix" icon="AwardMedal"></w-affix>
</w-textfield>

Disabled

Keep in mind that using disabled in its current form is an anti-pattern.

There will always be users who don't understand why an element is disabled, or users who can't even see that it is disabled because of poor lighting conditions or other reasons.

Please consider more informative alternatives before choosing to use disabled on an element.

html

<div class="flex flex-col space-y-32">
  <w-textfield label="Email" disabled value="ola.nordmann@finn.no"></w-textfield>
  <w-textfield label="Email" disabled></w-textfield>
</div>

Read only

The readonly boolean attribute makes the w-textfield's text content immutable. Unlike disabled the w-textfield remains focusable and the contents can still be copied. See MDN docs for more information.

html

<w-textfield 
  label="Email" 
  type="email" 
  value="ola.nordmann@finn.no" 
  readonly
></w-textfield>

Styling API

This section documents the supported styling hooks for <w-textfield>.

Use these hooks to customize appearance without relying on internal structure or selectors.

Before changing the default styles, remember that doing so can result in less consistent experiences for users across the product. Prefer defaults.

Prefer component tokens for size, spacing, and state styling.
Use parts only for small, local tweaks.
Avoid relying on internal class names or selectors.

Parts

The textfield exposes a minimal set of parts that can be targeted for last‑mile layout or typography tweaks.

Part	Targets	Typical use
`input`	native input element	minor typography or spacing tweaks

Example:

css

w-textfield::part(input) {
  letter-spacing: 0.5px;
}

Parts are intended as an escape hatch. Prefer component tokens for anything state‑ or size‑related.

Component tokens

Component tokens (--w-c-input-*) act as inputs to the textfield styling. They can be set directly on the component or inherited from a parent container.

These tokens are shared across textfield, textarea, and select for consistent form styling.

css

.form-section {
  --w-c-input-label-font-weight: 600;
  --w-c-input-help-text-color: var(--w-s-color-text);
}

Defaults are defined internally; setting a token is always optional.

Label tokens

Token	Purpose	Default
`--w-c-input-label-color`	label text color	`--w-s-color-text`
`--w-c-input-label-font-size`	label font size	`--w-font-size-s`
`--w-c-input-label-line-height`	label line height	`--w-line-height-s`
`--w-c-input-label-font-weight`	label font weight	`700`
`--w-c-input-label-padding-bottom`	space below label	`0.4rem`
`--w-c-input-label-cursor`	cursor when hovering label	`pointer`
`--w-c-input-label-display`	label display mode	`block`

Optional indicator tokens

When optional attribute is set, these tokens control the "(optional)" text styling:

Token	Purpose	Default
`--w-c-input-optional-color`	optional text color	`--w-s-color-text-subtle`
`--w-c-input-optional-font-size`	optional text font size	`--w-font-size-s`
`--w-c-input-optional-line-height`	optional text line height	`--w-line-height-s`
`--w-c-input-optional-font-weight`	optional text font weight	`400`
`--w-c-input-optional-padding-left`	space before optional text	`0.8rem`

Help text tokens

Token	Purpose	Default
`--w-c-input-help-text-color`	help text color (normal state)	`--w-s-color-text-subtle`
`--w-c-input-help-text-color-invalid`	help text color when invalid	`--w-s-color-text-negative`
`--w-c-input-help-text-font-size`	help text font size	`--w-font-size-xs`
`--w-c-input-help-text-line-height`	help text line height	`--w-line-height-xs`
`--w-c-input-help-text-margin-top`	space above help text	`0.4rem`
`--w-c-input-help-text-display`	help text display mode	`block`

Implementation notes

Shared token system

Textfield shares its label, optional indicator, and help text tokens with w-textarea and w-select. This ensures consistent form styling across all text input components.

Affix accessibility

Due to shadow DOM boundaries, affix content (prefix/suffix slots) cannot be connected to the input via ARIA references. For non-interactive affixes like currency symbols or unit labels, consider including that information in the main label or placeholder text instead for better screen reader support.

`<w-textfield>` API

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

Properties

Name	Type	Default	Summary
autocomplete	`HTMLInputElement["autocomplete"] \| undefined`	`-`	A space-separated string that hints to browsers what type of content it can suggest to autofill.
disabled	`boolean`	`false`	Makes the element not focusable and hides it from form submits
formatter (JS only)	`((value: string) => string) \| undefined`	`-`	Function to format value when the input field
handler (JS only)	`handler(e: Event) => void`	`-`	-
help-text	`string \| undefined`	`-`	Description shown below the input field
invalid	`boolean`	`false`	Mark the form field as invalid.
label	`string \| undefined`	`-`	Either a `label` or an `aria-label` must be provided.
max	`number \| undefined`	`-`	Use with `type="number"` to set the maximum allowed value.
max-length	`number \| undefined`	`-`	Deprecated: Use the native `maxlength` attribute
maxlength	`number \| undefined`	`-`	For `text`, `search`, `url`, `tel`, `email` and `password` fields, sets the maximum string length allowed.
min	`number \| undefined`	`-`	Use with `type="number"` to set the minimum allowed value.
min-length	`number \| undefined`	`-`	Deprecated: Use the native `minlength` attribute
minlength	`number \| undefined`	`-`	For `text`, `search`, `url`, `tel`, `email` and `password` fields, sets the minimum string length required.
name	`string \| undefined`	`-`	The name of the input field when submitting the form.
optional	`boolean`	`false`	Whether to show the optional indicator after the label.
pattern	`string \| undefined`	`-`	Sets a regular expression that the input's value must match to pass validation
placeholder	`string \| undefined`	`-`	Shown in the textfield when it doesn't have a value
prefixSlotChange (JS only)	`prefixSlotChange() => void`	`-`	-
read-only	`boolean`	`false`	Deprecated: Use the native readonly attribute instead.
readonly	`boolean`	`false`	Whether the input can be selected but not changed by the user.
required	`boolean`	`false`	Whether user input is required on the input before form submission.
resetFormControl (JS only)	`resetFormControl() => void`	`-`	-
size	`string \| undefined`	`-`	Sets the size (width) of the input field to fit the expected length of inputs.
step	`number \| undefined`	`-`	Forces `number` inputs to be a whole number of `step`
suffixSlotChange (JS only)	`suffixSlotChange() => void`	`-`	-
type	`string \| undefined`	`-`	The type of input.
value	`string \| undefined`	`-`	Lets you set the current value.

Property Details

autocomplete

A space-separated string that hints to browsers what type of content it can suggest to autofill.

Type: HTMLInputElement["autocomplete"] | undefined
Default: -

disabled

Keep in mind that using disabled in its current form is an anti-pattern.

There will always be users who don't understand why an element is disabled, or users who can't even see that it is disabled because of poor lighting conditions or other reasons.

Please consider more informative alternatives before choosing to use disabled on an element.

Type: boolean
Default: false

formatter (JS only)

Function to format value when the input field.

Only active when the input field does not have focus, similar to the accessible input masking example from Filament Group.

Type: ((value: string) => string) | undefined
Default: -

handler (JS only)

Type: handler(e: Event) => void
Default: -

help-text

Use in combination with invalid to show as a validation error message, or on its own to show a help text.

Type: string | undefined
Default: -

invalid

Mark the form field as invalid. Make sure to also set a help-text to help users fix the validation problem.

Type: boolean
Default: false

label

Either a label or an aria-label must be provided.

Type: string | undefined
Default: -

max

Use with type="number" to set the maximum allowed value.

Type: number | undefined
Default: -

max-length

Deprecated: Use the native maxlength attribute

Type: number | undefined
Default: -

maxlength

For text, search, url, tel, email and password fields, sets the maximum string length allowed.

Type: number | undefined
Default: -

min

Use with type="number" to set the minimum allowed value.

Type: number | undefined
Default: -

min-length

Deprecated: Use the native minlength attribute

Type: number | undefined
Default: -

minlength

For text, search, url, tel, email and password fields, sets the minimum string length required.

Type: number | undefined
Default: -

name

The name of the input field when submitting the form.

Type: string | undefined
Default: -

optional

Whether to show the optional indicator after the label.

Type: boolean
Default: false

pattern

Sets a regular expression that the input's value must match to pass validation

Type: string | undefined
Default: -

placeholder

Set a text that is shown in the textfield when it doesn't have a value.

Placeholder text should not be used as a substitute for labeling the element with a visible label.

Type: string | undefined
Default: -

prefixSlotChange (JS only)

Type: prefixSlotChange() => void
Default: -

read-only

Deprecated: Use the native readonly attribute instead.

Type: boolean
Default: false

readonly

Whether the input can be selected but not changed by the user.

Type: boolean
Default: false

required

Whether user input is required on the input before form submission.

Type: boolean
Default: false

resetFormControl (JS only)

Type: resetFormControl() => void
Default: -

size

Sets the size (width) of the input field to fit the expected length of inputs.

Type: string | undefined
Default: -

step

When used with number this attribute forces inputs to be a whole number of step.

For example with a step="5" only values that divide evenly on 5 are allowed. Using arrow up and down in the input field increments and decrements by 5.

Type: number | undefined
Default: -

suffixSlotChange (JS only)

Type: suffixSlotChange() => void
Default: -

type

The type of input.

Type: string | undefined
Default: -

value

Lets you set the current value.

Type: string | undefined
Default: -

Questions?

Feel free to ask any questions on usage in the Warp DS Slack channel: #warp-design-system

Text field - Elements ​

Accessibility ​

When used with an affix ​

Usage ​

Validation ​

Examples ​

Placeholder ​

Prefix label ​

Suffix Label ​

Prefix Search Icon ​

Suffix Search Icon ​

Suffix Clear Icon ​

Affix with arbitrary icon ​

Disabled ​

Read only ​

Styling API ​

Parts ​

Component tokens ​

Label tokens ​

Optional indicator tokens ​

Help text tokens ​

Implementation notes ​

Shared token system ​

Affix accessibility ​

<w-textfield> API ​

Properties ​

Property Details ​

autocomplete ​

disabled ​

formatter (JS only) ​

handler (JS only) ​

help-text ​

invalid ​

label ​

max ​

max-length ​

maxlength ​

min ​

min-length ​

minlength ​

name ​

optional ​

pattern ​

placeholder ​

prefixSlotChange (JS only) ​

read-only ​

readonly ​

required ​

resetFormControl (JS only) ​

size ​

step ​

suffixSlotChange (JS only) ​

type ​

value ​

Questions? ​

Text field - Elements

Accessibility

When used with an affix

Usage

Validation

Examples

Placeholder

Prefix label

Suffix Label

Prefix Search Icon

Suffix Search Icon

Suffix Clear Icon

Affix with arbitrary icon

Disabled

Read only

Styling API

Parts

Component tokens

Label tokens

Optional indicator tokens

Help text tokens

Implementation notes

Shared token system

Affix accessibility

`<w-textfield>` API

Properties

Property Details

autocomplete

disabled

formatter (JS only)

handler (JS only)

help-text

invalid

label

max

max-length

maxlength

min

min-length

minlength

name

optional

pattern

placeholder

prefixSlotChange (JS only)

read-only

readonly

required

resetFormControl (JS only)

size

step

suffixSlotChange (JS only)

type

value

Questions?