## `<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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete#value) 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#maxlength). |
| 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#maxlength) allowed. |
| min | `number \| undefined` | `-` | Use with `type="number"` to set the [minimum allowed value](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#minlength). |
| 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#minlength) required. |
| name | `string \| undefined` | `-` | The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions) that the input's value must [match to pass validation](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#pattern) |
| 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#input_types). |
| 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete#value) 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](https://filamentgroup.github.io/politespace/demo/demo.html).

- 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#maxlength).

- 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#maxlength) allowed.

- Type: `number | undefined`
- Default: `-`

#### min

Use with `type="number"` to set the [minimum allowed value](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#minlength).

- 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#minlength) required.

- Type: `number | undefined`
- Default: `-`

#### name

The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions) that the input's value must [match to pass validation](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#pattern)

- 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#input_types).

- Type: `string | undefined`
- Default: `-`

#### value

Lets you set the current value.

- Type: `string | undefined`
- Default: `-`

