# swc-text-field A single-line text field for entering and editing text. ```js import '@adobe/spectrum-wc/components/text-field/index.js'; // ``` ## Attributes | Name | Type | Default | Description | | ------------------------ | ------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `size` | `ElementSize` | `m` | Size of the control, label, and supporting text. | | `accessible-describedby` | `string \| undefined` | - | Space-separated description IDs in the field's document or shadow root. Combines with the visible description or error text. | | `accessible-label` | `string` | `''` | Accessible name supplied as `aria-label`. `accessible-labelledby` takes precedence when both are set. | | `accessible-labelledby` | `string \| undefined` | - | Space-separated label IDs in the field's document or shadow root. Takes precedence over `accessible-label` and the visible label. | | `value` | `string` | `''` | Current input value, normalized using the native input type's rules. | | `name` | `string \| undefined` | - | Name used for the field's entry in `FormData`. | | `type` | `TextFieldType` | `'text'` | Native input type. Unsupported values fall back to `text`. | | `placeholder` | `string` | `''` | Hint displayed when the field is empty. Does not replace a visible label. | | `pattern` | `string \| undefined` | - | Regular expression the entire nonempty value must match to pass validation. | | `inputmode` | `string \| undefined` | - | Suggests a virtual keyboard layout without changing validation. | | `autocomplete` | `TextFieldAutocomplete \| undefined` | - | Browser autofill hint, such as `email` or `username`. | | `maxlength` | `number \| undefined` | - | Maximum length for user input, measured in UTF-16 code units. | | `minlength` | `number \| undefined` | - | Minimum nonempty input length, measured in UTF-16 code units. Applies to user edits, not programmatically assigned values. | | `required` | `boolean` | `false` | Requires a nonempty value when the field participates in validation. | | `field-status` | `TextFieldStatus \| undefined` | - | Sets one interaction or validation status. `undefined` clears authored status. An eligible field with `invalid` fails validation; `valid` does not override native constraints. | | `label-position` | `TextFieldLabelPosition` | `'top'` | Position of the visible label relative to the control. | | `necessity-indicator` | `TextFieldNecessityIndicator` | `'icon'` | Necessity marker added to a visible label. `icon` shows an asterisk only when required; `label` shows `(required)` or `(optional)`. | ## Slots | Name | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `label` | Visible label. Clicking it focuses the input. | | `prefix` | Non-interactive content before the input, such as an icon, symbol, or avatar. | | `description` | Help text included in the accessible description. While `field-status="invalid"`, shown in the error color unless replaced by supplied `error-text`. | | `error-text` | Error text shown, included in the accessible description, and used as the validation message while `field-status="invalid"`. Supply translated text when needed. | ## Events | Name | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `change` | Fires when the user commits an edited value, such as on blur. Bubbles and crosses shadow boundaries; not cancelable. | | `input` | Fires during user edits, after the value, form data, and validity update. Bubbles and crosses shadow boundaries; not cancelable. | | `invalid` | Fires on the host when validation fails. Cancelable; does not bubble or cross shadow boundaries. Canceling suppresses native validation UI, not the failure. | ## CSS Custom Properties | Name | Description | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `--swc-field-label-max-inline-size` | Maximum label inline size for `label-position="side"`. Defaults to `50%` of the field's inline size. | | `--swc-field-input-min-inline-size` | Minimum control inline size. Defaults to the control height for the selected `size`. | | `--swc-field-input-max-inline-size` | Maximum control inline size. Defaults to the field width for the selected `size`. | | `--swc-text-field-padding-block` | Block-axis control padding. Varies with `size`. | | `--swc-text-field-padding-inline` | Inline-axis control padding. Varies with `size`. | | `--swc-text-field-affix-gap` | Spacing between prefix content and the input. Varies with `size`. | | `--swc-form-field-row-gap` | Block-axis spacing between the label, control, and help text. Varies with `size`. | | `--swc-form-field-necessity-gap` | Inline spacing between the label and its necessity marker. Varies with `size`. | | `--swc-text-field-font-size` | Input and prefix font size. Varies with `size`. | | `--swc-text-field-line-height` | Input and prefix line height. Defaults to `normal`. | | `--swc-text-field-border-radius` | Control corner radius. Varies with `size`. | | `--swc-text-field-border-color-default` | Border color when neither hovered nor focused. Defaults vary with `field-status`. | | `--swc-text-field-border-color-hover` | Border color when hovered without focus. Defaults vary with `field-status`. | | `--swc-text-field-border-color-focus` | Border color when focused without hover. Defaults vary with `field-status`. | | `--swc-text-field-border-color-focus-hover` | Border color when both hovered and focused. Defaults vary with `field-status`. | | `--swc-text-field-validation-icon-size` | Inline and block size of the invalid-status icon. Varies with `size`. | | `--swc-form-field-label-font-size` | Visible label font size. Defaults to the typography scale for the selected `size`. | | `--swc-form-field-description-font-size` | Description and error-text font size. Defaults to the typography scale for the selected `size`. |