@gravity-ui/uikit
Version:
Gravity UI base styling and components
151 lines (111 loc) • 11.8 kB
Markdown
# TextInput
```tsx
import {TextInput} from '@gravity-ui/uikit';
```
TextInput allow users to enter text into a UI.
## Appearance
The appearance of `TextInput` is controlled by the `view` and `pin` properties.
### View
`normal` - the main view of `TextInput` (used by default).
`clear` - can be used with a custom wrapper for `TextInput`.
```tsx
<TextInput view="normal" />
<TextInput view="clear" />
```
### Pin
Allows you to control view of right and left edges of `TextInput`'s border.
```tsx
<TextInput pin="round-brick" />
<TextInput pin="brick-brick" />
<TextInput pin="brick-round" />
```
## States
### Disabled
The state of the `TextInput` where you don't want the user to be able to interact with the component.
```tsx
<TextInput disabled />
```
### Error
The state of the `TextInput` in which you want to indicate incorrect user input. To change `TextInput` appearance, use the `validationState` property with the `"invalid"` value. An optional message text can be added via the `errorMessage` property. By default, message text is rendered outside the component.
This behaviour can be changed with the `errorPlacement` property.
```tsx
<TextInput errorMessage="Error message" validationState="invalid" />
<TextInput errorPlacement="inside" errorMessage="Error message" validationState="invalid" />
```
## Size
`s` – Used when standard controls are too big (tables, small cards).
`m` – Basic size, used in most components.
`l` – Basic controls performed in a page's header, modal windows, or pop-ups.
`xl` – Used on promo and landing pages.
```tsx
<TextInput size="s" />
<TextInput size="m" />
<TextInput size="l" />
<TextInput size="xl" />
```
## Label
Allows you to set the label to the left of control.
- label occupies the leftmost position relative to the control. That is, the elements added via `startContent` property will be located to the right.
- label can take up no more than half the width of the entire TextInput's space.
```tsx
<TextInput label="Label" />
```
## Additional content
### Start content
Allows you to add content to the left of the control (or to the right in case of using [rtl](https://developer.mozilla.org/en-US/docs/Glossary/RTL)). Located to the left (or to the right in case of using rtl) of the label added via `label` property.
```tsx
<TextInput startContent={<Label>Left</Label>} />
```
### End content
Allows you to add content to the right (or to the left in case of using [rtl](https://developer.mozilla.org/en-US/docs/Glossary/RTL)) of the control. Located to the right (or to the left in case of using rtl) of the clear button added via `hasClear` property.
```tsx
<TextInput endContent={<Label>Right</Label>} />
```
## Properties
| Name | Description | Type | Default |
| :-------------- | :---------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------: | :-------------: |
| autoComplete | The control's `autocomplete` attribute | `boolean` `string` | |
| autoFocus | The control's `autofocus` attribute | `boolean` | |
| className | The control's wrapper class name | `string` | |
| controlProps | The control's html attributes | `React.InputHTMLAttributes<HTMLInputElement>` | |
| controlRef | React ref provided to the control | `React.Ref<HTMLInputElement>` | |
| defaultValue | The control's default value, used when the component is not controlled | `string` | |
| disabled | Indicates that the user cannot interact with the control | `React.ReactNode` | |
| endContent | User`s node rendered after input node, clear button and error icon | `string` | |
| errorMessage | Error text | `string` | |
| errorPlacement | Error placement | `outside` `inside` | `outside` |
| hasClear | Shows the icon for clearing control's value | `boolean` | `false` |
| id | The control's `id` attribute | `string` | |
| label | Help text rendered to the left of the input node | `string` | |
| name | The `name` attribute of the control. If unspecified, it will be autogenerated if not specified | `string` | |
| note | An optional element displayed under the bottom-right corner of the control that shares a space with the error container | `React.ReactNode` | |
| onBlur | Fires when the control lost focus. Provides focus event as a callback's argument | `function` | |
| onChange | Fires when the input’s value is changed by the user. Provides change event as an callback's argument | `function` | |
| onFocus | Fires when the control gets focus. Provides focus event as a callback's argument | `function` | |
| onKeyDown | Fires when a key is pressed. Provides keyboard event as a callback's argument | `function` | |
| onKeyUp | Fires when a key is released. Provides keyboard event as a callback's argument | `function` | |
| onUpdate | Fires when the input’s value is changed by the user. Provides new value as an callback's argument | `function` | |
| pin | The control's border view | `string` | `'round-round'` |
| placeholder | Text that appears in the control when it has no value set | `string` | |
| qa | Test ID attribute (`data-qa`) | `string` |
| readOnly | Indicates that the user cannot change control's value | `boolean` | `false` |
| size | The size of the control | `"s"` `"m"` `"l"` `"xl"` | `"m"` |
| startContent | User`s node rendered before label and input node | `React.ReactNode` | |
| tabIndex | The `tabindex` attribute of the control | `string` | |
| type | The type of the control | `"email"` `"number"` `"password"` `"search"` `"tel"` `"text"` `"url"` | |
| validationState | Validation state | `"invalid"` | |
| value | The value of the control | `string` | |
| view | The view of the control | `"normal"` `"clear"` | `"normal"` |
## CSS API
| Name | Description |
| :----------------------------------- | :-------------------------------------------------- |
| `--g-text-input-text-color` | Text color |
| `--g-text-input-label-color` | Label color |
| `--g-text-input-placeholder-color` | Placeholder color |
| `--g-text-input-background-color` | Background color |
| `--g-text-input-border-radius` | Border radius |
| `--g-text-input-border-width` | Border width |
| `--g-text-input-border-color` | Border color |
| `--g-text-input-border-color-hover` | Border color if hovered |
| `--g-text-input-border-color-active` | Border color if active |
| `--g-text-input-focus-outline-color` | Outline color if focused (by default not presented) |