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. If you use the tooltip property, the tooltip component's exported parts can also be styled from the textfield.

Part	Targets	Typical use
`base`	wrapper around the component internals
`input`	native input element	minor typography or spacing tweaks
`mask-wrapper`	wrapper around the input mask	formatting-related layout tweaks
`mask`	formatted value shown when the input is not focused	typography for formatter output
`help-text`	help text container below the field	small typography tweaks
`label`	label element above the field	small label layout tweaks
`tooltip-target`	info icon button rendered when `tooltip` is set	small icon button alignment tweaks
`tooltip`	tooltip surface exported by `w-tooltip`	tooltip surface tweaks
`arrow`	tooltip arrow exported by `w-tooltip`	tooltip arrow tweaks
`beak`	tooltip beak exported by `w-tooltip`	tooltip beak tweaks
`hover-bridge`	tooltip hover bridge exported by `w-tooltip`	tooltip hover behavior tweaks

Example:

css

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

w-textfield::part(label) {
  padding-bottom: 0.6rem;
}

Parts are intended as an escape hatch. Prefer component tokens where possible.

Component tokens

Textfield has its own --w-c-textfield-* tokens for the input element. It also shares --w-c-input-* tokens with other form components for labels, optional indicators, and help text.

css

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

w-textfield.search {
  --w-c-textfield-padding-left: 12px;
  --w-c-textfield-color-placeholder: var(--w-s-color-text-subtle);
}

Textfield tokens

Token	Purpose	Default
`--w-c-textfield-padding-left`	input left padding	`8px`
`--w-c-textfield-padding-right`	input right padding	`8px`
`--w-c-textfield-line-height`	input line height	`--w-line-height-m`
`--w-c-textfield-font-size`	input font size	`--w-font-size-m`
`--w-c-textfield-color-border`	border color	`--w-s-color-border-strong`
`--w-c-textfield-color`	input text color	`--w-s-color-text`
`--w-c-textfield-background`	input background color	`--w-s-color-background`
`--w-c-textfield-color-border-active`	border color while active	`--w-s-color-border-selected`
`--w-c-textfield-color-border-hover`	border color on hover	`--w-s-color-border-strong-hover`
`--w-c-textfield-outline-focus`	focus outline	`2px solid var(--w-s-color-border-focus)`
`--w-c-textfield-outline-offset`	focus outline offset	`-2px`
`--w-c-textfield-color-border-invalid`	border color when invalid	`--w-s-color-border-negative`
`--w-c-textfield-color-invalid`	text color when invalid	`--w-s-color-text-negative`
`--w-c-textfield-outline-invalid`	outline when invalid	`2px solid var(--w-s-color-border-negative)`
`--w-c-textfield-color-border-invalid-hover`	border color when invalid and hovered	`--w-s-color-border-negative-hover`
`--w-c-textfield-color-border-disabled`	border color when disabled	`--w-s-color-border-disabled`
`--w-c-textfield-color-disabled`	text color when disabled	`--w-s-color-text-disabled`
`--w-c-textfield-color-background-disabled`	background color when disabled	`--w-s-color-background-disabled-subtle`
`--w-c-textfield-color-placeholder`	placeholder text color	`--w-s-color-text-placeholder`

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 the optional attribute is set and the field is not required, these tokens control the optional indicator after the label.

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.4rem`

Help text tokens

Token	Purpose	Default
`--w-c-input-help-text-color`	help text color	`--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`

Prefix and suffix slots

Prefix and suffix content is slotted, so it remains in light DOM and should usually be styled directly where it is used.

css

w-textfield w-affix {
  color: var(--w-s-color-text-subtle);
}

When prefix or suffix content is present, the textfield adjusts input padding internally to make room for it.

Implementation notes

Shared token system

Textfield shares its label, optional indicator, and help text tokens with other form components. This keeps common form styling consistent across inputs.

Formatter mask

When formatter is set, the component can render a formatted mask over the input while the input is not focused. Use the mask and mask-wrapper parts only for small display tweaks to this formatted value.

Affix accessibility

Due to shadow DOM boundaries, affix content from the prefix and suffix slots cannot be connected to the input with ARIA references from inside the component. For non-interactive affixes like currency symbols or unit labels, consider including that information in the main label or placeholder text as well.

`<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
helpTextSlotChange (JS only)	`helpTextSlotChange() => void`	`-`	-
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`	`-`	-
tooltip	`string \| undefined`	`-`	Supplementary information that should show in a tooltip behind an information icon after the label.
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: -

helpTextSlotChange (JS only)

Type: helpTextSlotChange() => void
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: -

Supplementary information that should show in a tooltip behind an information icon after the label.

You must provide a label to be able to show an info icon with a tooltip.

Type: string | undefined
Default: -

type

The type of input.

Type: string | undefined
Default: -

value

Lets you set the current value.

Type: string | undefined
Default: -

Types

((value: string) => string) | undefined

{ } | undefined

HTMLInputElement["autocomplete"] | undefined

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 ​

Textfield tokens ​

Label tokens ​

Optional indicator tokens ​

Help text tokens ​

Prefix and suffix slots ​

Implementation notes ​

Shared token system ​

Formatter mask ​

Affix accessibility ​

<w-textfield> API ​

Properties ​

Property Details ​

autocomplete ​

disabled ​

formatter (JS only) ​

handler (JS only) ​

help-text ​

helpTextSlotChange (JS only) ​

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) ​

tooltip ​

type ​

value ​

Types ​

((value: string) => string) | undefined ​

HTMLInputElement["autocomplete"] | undefined ​

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

Textfield tokens

Label tokens

Optional indicator tokens

Help text tokens

Prefix and suffix slots

Implementation notes

Shared token system

Formatter mask

Affix accessibility

`<w-textfield>` API

Properties

Property Details

autocomplete

disabled

formatter (JS only)

handler (JS only)

help-text

helpTextSlotChange (JS only)

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)

tooltip

type

value

Types

((value: string) => string) | undefined

HTMLInputElement["autocomplete"] | undefined

Questions?