# gds-input

**Class**: `GdsInput`

**Tag**: `<gds-input>`


## Properties

> Some properties accept design token names. Use `get_tokens` with the appropriate category to discover valid token names and their resolved values.

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `width` | `string \| undefined` | `-` | Style Expression Property that controls the `width` property. Supports space tokens and all valid CSS `width` values. |
| `'min-width'` | `string \| undefined` | `-` | Style Expression Property that controls the `min-width` property. Supports space tokens and all valid CSS `min-width` values. |
| `'max-width'` | `string \| undefined` | `-` | Style Expression Property that controls the `max-width` property. Supports space tokens and all valid CSS `max-width` values. |
| `'inline-size'` | `string \| undefined` | `-` | Style Expression Property that controls the `inline-size` property. Supports space tokens and all valid CSS `inline-size` values |
| `'min-inline-size'` | `string \| undefined` | `-` | Style Expression Property that controls the `min-inline-size` property. Supports space tokens and all valid CSS `min-inline-size` values. |
| `'max-inline-size'` | `string \| undefined` | `-` | Style Expression Property that controls the `max-inline-size` property. Supports space tokens and all valid CSS `max-inline-size` values. |
| `margin` | `string \| undefined` | `-` | Style Expression Property that controls the `margin` property. Only accepts space tokens. |
| `'margin-inline'` | `string \| undefined` | `-` | Style Expression Property that controls the `margin-inline` property. Only accepts space tokens. |
| `'margin-block'` | `string \| undefined` | `-` | Style Expression Property that controls the `margin-block` property. Only accepts space tokens. |
| `'align-self'` | `string \| undefined` | `-` | Style Expression Property that controls the `align-self` property. Supports all valid CSS `align-self` values. |
| `'justify-self'` | `string \| undefined` | `-` | Style Expression Property that controls the `justify-self` property. Supports all valid CSS `justify-self` values. |
| `'place-self'` | `string \| undefined` | `-` | Style Expression Property that controls the `place-self` property. Supports all valid CSS `place-self` values. |
| `'grid-column'` | `string \| undefined` | `-` | Style Expression Property that controls the `grid-column` property. Supports all valid CSS grid-column values. Documentation: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column |
| `'grid-row'` | `string \| undefined` | `-` | Style Expression Property that controls the `grid-row` property. Supports all valid CSS `grid-row` values. |
| `'grid-area'` | `string \| undefined` | `-` | Style Expression Property that controls the `grid-area` property. Supports all valid CSS `grid-area` values. |
| `flex` | `string \| undefined` | `-` | Style Expression Property that controls the `flex` property. Supports all valid CSS `flex` values. |
| `order` | `string \| undefined` | `-` | Style Expression Property that controls the `order` property. Supports all valid CSS `order` values. |
| `supportingText` | `string` | `-` | The supporting text displayed between the label and the field. This text provides additional context or information to the user. |
| `showExtendedSupportingText` | `boolean` | `-` | Whether the supporting text should be displayed or not. |
| `clearable` | `boolean` | `-` | Whether the field should be clearable or not. Clearable fields will display a clear button when the field has a value. |
| `maxlength` | `number` | `-` | The maximum number of characters allowed in the field. |
| `size` | `'large' \| 'small'` | `-` | Controls the font-size of texts and height of the field. |
| `plain` | `boolean` | `-` | Hides the header and the footer, while still keeping the accessible label  Always set the `label` attribute, and if you need to hide it, add this attribute and keep `label` set. |
| `type` | `\| 'date'     \| 'datetime-local'     \| 'email'     \| 'number'     \| 'password'     \| 'search'     \| 'tel'     \| 'text'     \| 'time'     \| 'url'` | `-` | The type of input. Works the same as a native `<input>` element, but only a subset of types are supported. Defaults to `text`. |
| `min` | `number \| string \| undefined` | `-` | The input's minimum value. Only applies to date and number input types. |
| `max` | `number \| string \| undefined` | `-` | The input's maximum value. Only applies to date and number input types. |
| `step` | `number \| 'any' \| undefined` | `-` | 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. |
| `autocapitalize` | `'off' \| 'none' \| 'on' \| 'sentences' \| 'words' \| 'characters'` | `-` | Controls whether and how text input is automatically capitalized as it is entered by the user. |
| `autocorrect` | `boolean` | `-` | Indicates whether the browser's autocorrect feature is on or off. |
| `autocomplete` | `string \| undefined` | `-` | Specifies what permission the browser has to provide assistance in filling out form field values. Refer to [this page on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) for available values. |
| `autofocus` | `boolean` | `-` | Indicates that the input should receive focus on page load. |
| `enterkeyhint` | `\| 'enter'     \| 'done'     \| 'go'     \| 'next'     \| 'previous'     \| 'search'     \| 'send' \| undefined` | `-` | Used to customize the label or icon of the Enter key on virtual keyboards. |
| `spellcheck` | `boolean` | `-` | Enables spell checking on the input. |
| `inputmode` | `\| 'none'     \| 'text'     \| 'decimal'     \| 'numeric'     \| 'tel'     \| 'search'     \| 'email'     \| 'url' \| undefined` | `-` | Tells the browser what type of data will be entered by the user, allowing it to display the appropriate virtual keyboard on supportive devices. |
| `charCounterCallback` | `any` | `-` | This callback allows for customization of the character counter. It should return a tuple with the first value being the number of remaining characters, and the second value being the variant of the badge. If the second value is `false`, no badge will be displayed. |
| `selectionStart` | `any` | `-` | Sets the position of the start of the current text selection in the input element. |
| `selectionEnd` | `any` | `-` | Sets the position of the end of the current text selection in the input element. |
| `selectionDirection` | `any` | `-` | Sets the direction of the current text selection in the input element. |
| `value` | `string` | `-` | Get or set the value of the form control. |
| `validator` | `GdsValidator \| undefined` | `-` | A validator that can be used to validate the form control and set an error message. |
| `required` | `boolean` | `-` | The required attribute can be used to communicate to users of assistive technology that the control is required. Validation still needs to be done in a validator or equivalent. |
| `errorMessage` | `string` | `-` | This can be used to manually control the error message that will be displayed when the control is invalid. |
| `invalid` | `any` | `-` | Validation state of the form control. Setting this to true triggers the invalid state of the control. |
| `label` | `string` | `-` | The label of the form control. |
| `name` | `string` | `-` |  |
| `disabled` | `boolean` | `-` | If the input is Disabled |
| `syncFirstRender` | `boolean` | `-` | Force the element to perform a synchronous first render and apply style expression properties in `connectedCallback`.  This guarantees that the child DOM always remains projected in DOM, since the element will attach the shadowRoot and run the first render pass in the same event loop cycle, and that declarative layout will be applied once slotted DOM is projected.  Note: This will cause the first render pass to be blocking. Use sparingly and only when necessary, such as when the element needs to be measured synchronously after being added to the DOM. |


## Events

| Name | Type | Description |
|------|------|-------------|
| `gds-input-cleared` | `CustomEvent<any>` | Fired when the clear button is clicked. |


## Slots

| Name | Description |
|------|-------------|
| `lead` | Accepts `gds-icon-[ICON_NAME]`. Use this to place an icon in the start of the field. |
| `trail` | Accepts `gds-badge`. Use this to place a badge in the field, for displaying currency for example. |
| `extended-supporting-text` | A longer supporting text can be placed here. It will be displayed in a panel when the user clicks the info button. |


## Form Control

This component is a form control and inherits form-related properties and methods.