> For the complete documentation index, see [llms.txt](https://bctc.gitbook.io/vant-react-official-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bctc.gitbook.io/vant-react-official-docs/field.md).

# Field

### [Demo](https://vant.bctc.io/?path=/story/field--basic-usage)

#### Install

```
import React from 'react';
import { Field } from 'vant-react';
```

## Usage

#### Basic Usage

```
<Field />
```

#### Require Field

```
<Field label='Required' required />
```

#### Custom Types

```
<Field label='Text' type='text' />
<Field label='Phone' type='tel' />
<Field label='Digit' type='digit' />
<Field label='Number' type='number' />
<Field label='Password' type='password' />
```

#### Disabled

```
<Field disabled value='Input Disabled' />
<Field readonly value='Input Readonly' />
```

#### Colon

```
<Field label='Colon' colon />
```

#### ShowIcon

```
<Field label='Left Icon' leftIcon='music-o' />
<Field label='Right Icon' rightIcon='success' />
<Field labelWidth='150px' label='Label Icon' labelIcon='search' />
```

#### Field Events

```
const [value, setValue] = useState('');
const [isFocus, setFocus] = useState(false);

<p>Value: {value}</p>

<Field
        leftIcon='smile-o'
        placeholder='Show clear icon'
        rightIcon='success'
        value={value}
        input={(e) => setValue(e.target.value)}
        clear={() => setValue('')}
        clearable
/>
<Field 
        leftIcon='smile-o' 
        placeholder='Click event' 
        rightIcon='success' 
/>
<Field
        leftIcon='smile-o'
        placeholder='Input focus state'
        rightIcon={isFocus ? 'success' : 'cross'}
        focus={() => setFocus(true)}
        blur={() => setFocus(false)}
/>
<Field
        leftIcon='smile-o'
        placeholder='Input click event'
        clickable
        clickInput={() => alert('Input clicked')}
/>
<Field
        leftIcon='smile-o'
        rightIcon='fire-o'
        placeholder='Input left and right icon click'
        clickable
        clickLeftIcon={() => alert('Left Icon Clicked')}
        clickRightIcon={() => alert('Right Icon Clicked')}
/>
```

#### Field Ref

```
const [containerRef, setContainerRef] = useState(null);
const [fieldRef, setFieldRef] = useState(null);
const [clickOutside, setClickOutside] = useState(false);

window.addEventListener('click', (e) => {
    if (
      containerRef !== undefined &&
      containerRef.current &&
      !containerRef.current.contains(e.target)
    ) {
      setClickOutside(true);
    } else {
      setClickOutside(false);
    }
  });


<p>
    Container Ref element name:
    {
      containerRef && containerRef.current.localName
    }
</p>
<p>
    Field Ref element name:{' '}
    {
      fieldRef && fieldRef.current.localName
    }
</p>

<Field
        placeholder={`Click outside? ${clickOutside}`}
        leftIcon='music-o'
        rightIcon='success'
        getContainerRef={(ref) => setContainerRef(ref)}
        getFieldRef={(ref) => setFieldRef(ref)}
/>
```

#### Auto Focus

```
<Field label='Error input' error errorMessage='Invalid input info' />
```

#### Error Info

```
<Field label='Error input' error errorMessage='Invalid input info' />
```

#### Max Length Word Limit

```
const [value, setValue] = useState('');

<Field
        value={value}
        input={(e) => setValue(e.target.value)}
        label='Max length'
        maxLength={5}
        showWordLimit
/>
```

#### Field With Button

```
<Field
        label='SMS'
        placeholder='SMS'
        button=
        {
          <Button
            size='small'
            click={() => alert('Message sent!')}
            text='Send SMS'
            type='primary'
          />
        }
/>
```

#### Formatter

```
const [value, setValue] = useState('');

<Field
        label='Text Only'
        placeholder='No Numbers'
        value={value}
        input={(e) => setValue(e.target.value)}
        formatter={(value) => pattern.test(value)}
/>
```

#### Label Utilities

```
<Field label='Long 220px label' labelClass='pant' labelWidth='220px' />
```

#### Label Input Alignment

```
<Field
      label='Label Center'
      placeholder='Input Right'
      labelWidth='190px'
      labelAlign='center'
      inputAlign='right'
/>
<Field
      label='Label Right'
      placeholder='Input Center'
      labelWidth='190px'
      inputAlign='center'
      labelAlign='right'
/>
<Field
      label='Error Center'
      placeholder='Input Center'
      labelWidth='190px'
      inputAlign='center'
      labelAlign='right'
      error
      errorMessage='Something went wrong'
      errorAlign='center'
/>
<Field
      label='Error Right'
      placeholder='Input Center'
      labelWidth='190px'
      inputAlign='center'
      labelAlign='right'
      errorMessage='Something went wrong'
      errorAlign='right'
      error
/>
```

#### Auto Resize

```
<Field />
```

## API

#### Props

| Attribute       | Description                                              | Type             | Default | Required   |
| --------------- | -------------------------------------------------------- | ---------------- | ------- | ---------- |
| `value`         | Filed value                                              | ***string***     | -       | *optional* |
| `type`          | Can be set to `text` `tel` `digit` `number` `password`   | ***string***     | `text`  | *optional* |
| `label`         | Field label                                              | ***string***     | -       | *optional* |
| `name`          | Name                                                     | ***string***     | -       | *optional* |
| `placeholder`   | Placeholder                                              | ***string***     | -       | *optional* |
| `readonly`      | Whether to be readonly                                   | ***boolean***    | `false` | *optional* |
| `disabled`      | Whether to display colon after label                     | ***boolean***    | `false` | *optional* |
| `colon`         | Whether to be readonly                                   | ***boolean***    | `false` | *optional* |
| `labelIcon`     | Label icon that appears on the left                      | ***string***     | -       | *optional* |
| `leftIcon`      | Left side icon name                                      | ***string***     | -       | *optional* |
| `rightIcon`     | Right side icon name                                     | ***string***     | -       | *optional* |
| `clearable`     | Whether to be clearable                                  | ***boolean***    | `false` | *optional* |
| `clickable`     | Whether to show click feedback when clicked              | ***boolean***    | `false` | *optional* |
| `autofocus`     | Whether to auto focus                                    | ***boolean***    | `false` | *optional* |
| `error`         | Whether to show error info                               | ***boolean***    | `false` | *optional* |
| `error-message` | Error message                                            | ***string***     | -       | *optional* |
| `maxLength`     | Max length of value                                      | ***number***     | -       | *optional* |
| `showWordLimit` | Whether to show word limit, need to set `maxLength` prop | ***boolean***    | `false` | *optional* |
| `formatter`     | Input value formatter                                    | ***Function***   | `true`  | *optional* |
| `labelClass`    | Label className                                          | ***string***     | -       | *optional* |
| `labelWidth`    | Label width                                              | ***string***     | -       | *optional* |
| `labelAlign`    | Label align, can be set to`center` `right`               | ***TAlignment*** | `left`  | *optional* |
| `inputAlign`    | Input align, can be set to`center` `right`               | ***TAlignment*** | `left`  | *optional* |
| `errorAlign`    | Error message align, can be set to`center` `right`       | ***TAlignment*** | `left`  | *optional* |
| `required`      | Whether to show required mark                            | ***boolean***    | `false` | *optional* |
| `border`        | Whether to show inner border                             | ***boolean***    | `true`  | *optional* |

#### Event

| Event             | Description                                            | Arguments       |
| ----------------- | ------------------------------------------------------ | --------------- |
| `input`           | Triggered when input value changed                     | *value: String* |
| `clear`           | Triggered when click clear icon                        | *event: Event*  |
| `click`           | Triggered when click Field                             | *event: Event*  |
| `clickInput`      | Triggered when click input                             | *event: Event*  |
| `focus`           | Triggered when input gets focus                        | *event: Event*  |
| `blur`            | Triggered when input loses focus                       | *event: Event*  |
| `clickLeftIcon`   | Triggered when click the left icon of Field            | *event: Event*  |
| `clickRightIcon`  | Triggered when click the right icon of Field           | *event: Event*  |
| `getContainerRef` | Triggered when container ref is not undefined nor null | *event: Event*  |
| `getFieldRef`     | Triggered when Field ref is not undefined nor null     | *event: Event*  |
| `focus`           | Triggered when input gets focus                        | *event: Event*  |