metamask-extension/ui/components/component-library/text-field-base/README.mdx

import { Story, Canvas, ArgsTable } from '@storybook/addon-docs';

import { TextFieldBase } from './text-field-base';

### This is a base component. It should not be used in your feature code directly but as a "base" for other UI components

# TextFieldBase

The `TextFieldBase` is the base component for all text fields. It should not be used directly. It functions as both a uncontrolled and controlled input.

<Canvas>
  <Story id="components-componentlibrary-textfieldbase--default-story" />
</Canvas>

## Props

The `TextFieldBase` accepts all props below as well as all [Box](/docs/components-ui-box--default-story#props) component props

<ArgsTable of={TextFieldBase} />

### Size

Use the `size` prop to set the height of the `TextFieldBase`.

Possible sizes include:

- `sm` 32px
- `md` 40px
- `lg` 48px

Defaults to `md`

<Canvas>
  <Story id="components-componentlibrary-textfieldbase--size" />
</Canvas>

```jsx
import { SIZES } from '../../../helpers/constants/design-system';
import { TextFieldBase } from '../../component-library';

<TextFieldBase size={SIZES.SM} />
<TextFieldBase size={SIZES.MD} />
<TextFieldBase size={SIZES.LG} />
```

### Type

Use the `type` prop to change the type of input.

Possible types include:

- `text`
- `number`
- `password`

Defaults to `text`.

<Canvas>
  <Story id="components-componentlibrary-textfieldbase--type" />
</Canvas>

```jsx
import { TextFieldBase } from '../../component-library';

<TextFieldBase type="text" /> // (Default)
<TextFieldBase type="number" />
<TextFieldBase type="password" />
```

### Truncate

Use the `truncate` prop to truncate the text of the the `TextFieldBase`. Defaults to `true`.

<Canvas>
  <Story id="components-componentlibrary-textfieldbase--truncate" />
</Canvas>

```jsx
import { TextFieldBase } from '../../component-library';

<TextFieldBase truncate />; // truncate is set to `true` by default
<TextFieldBase truncate={false} />;
```

### Left Accessory Right Accessory

Use the `leftAccessory` and `rightAccessory` props to add components such as icons or buttons to either side of the `TextFieldBase`.

<Canvas>
  <Story id="components-componentlibrary-textfieldbase--left-accessory-right-accessory" />
</Canvas>

```jsx
import { COLORS, SIZES, DISPLAY } from '../../../helpers/constants/design-system';
import { ButtonIcon, Icon, ICON_NAMES, TextFieldBase } from '../../component-library';

<TextFieldBase
  placeholder="Search"
  leftAccessory={
    <Icon
      color={COLORS.ICON_ALTERNATIVE}
      name={ICON_NAMES.SEARCH}
    />
  }
/>

<TextFieldBase
  placeholder="Public address (0x), or ENS"
  rightAccessory={
    <ButtonIcon
      iconName={ICON_NAMES.SCAN_BARCODE}
      ariaLabel="Scan QR code"
      iconProps={{ color: COLORS.PRIMARY_DEFAULT }}
    />
  }
/>

<TextFieldBase
  placeholder="Enter amount"
  type="number"
  truncate
  leftAccessory={<SelectTokenComponent />}
  rightAccessory={<TokenValueInUSDComponent />}
/>

<TextFieldBase
  placeholder="Public address (0x), or ENS"
  truncate
  leftAccessory={<AvatarAccount />}
  rightAccessory={
    isAddressValid && (
      <Icon
        name={ICON_NAMES.CHECK}
        color={COLORS.SUCCESS_DEFAULT}
      />
    )
  }
/>
```

### Input Ref

Use the `inputRef` prop to access the ref of the `<input />` html element of `TextFieldBase`. This is useful for focusing the input from a button or other component.

<Canvas>
  <Story id="components-componentlibrary-textfieldbase--input-ref" />
</Canvas>

```jsx
import { Button, TextFieldBase } from '../../component-library';

const inputRef = useRef(null);
const [value, setValue] = useState('');
const handleOnClick = () => {
  inputRef.current.focus();
};
const handleOnChange = (e) => {
  setValue(e.target.value);
};

<TextFieldBase
  inputRef={inputRef}
  value={value}
  onChange={handleOnChange}
/>
<Button marginLeft={1} onClick={handleOnClick}>
  Edit
</Button>
```

### Input Component

Use the `InputComponent` prop change the component used for the input element. This is useful for replacing the base input with a custom input while retaining the functionality of the `TextFieldBase`.

Defaults to the [Text](/docs/components-componentlibrary-text--default-story) component

To function fully the custom component should accept the following props:

- `aria-invalid`
- `as`
- `autoComplete`
- `autoFocus`
- `backgroundColor`
- `defaultValue`
- `disabled`
- `focused`
- `id`
- `margin`
- `maxLength`
- `name`
- `onBlur`
- `onChange`
- `onFocus`
- `padding`
- `paddingLeft`
- `paddingRight`
- `placeholder`
- `readOnly`
- `ref`
- `required`
- `value`
- `variant`
- `type`

<Canvas>
  <Story id="components-componentlibrary-textfieldbase--input-component" />
</Canvas>

```jsx
import { TextFieldBase, Icon, ICON_NAMES } from '../../component-library';

// should map the props to the custom input component
const CustomInputComponent = () => <div>{/* Custom input component */}</div>;

const TextFieldCustomInput = (args) => (
  <TextFieldBase
    size={SIZES.LG}
    InputComponent={CustomInputComponent}
    leftAccessory={
      <Icon color={COLORS.ICON_ALTERNATIVE} name={ICON_NAMES.WALLET} />
    }
  />
);
```

### Auto Complete

Use the `autoComplete` prop to set the autocomplete html attribute. It allows the browser to predict the value based on earlier typed values.

<Canvas>
  <Story id="components-componentlibrary-textfieldbase--auto-complete" />
</Canvas>

```jsx
import { TextFieldBase } from '../../component-library';

<TextFieldBase type="password" autoComplete />;
```

### Auto Focus

Use the `autoFocus` prop to focus the `TextFieldBase` during the first mount

<Canvas>
  <Story id="components-componentlibrary-textfieldbase--auto-focus" />
</Canvas>

```jsx
import { TextFieldBase } from '../../component-library';

<TextFieldBase autoFocus />;
```

### Default Value

Use the `defaultValue` prop to set the default value of the `TextFieldBase`

<Canvas>
  <Story id="components-componentlibrary-textfieldbase--default-value" />
</Canvas>

```jsx
import { TextFieldBase } from '../../component-library';

<TextFieldBase defaultValue="default value" />;
```

### Disabled

Use the `disabled` prop to set the disabled state of the `TextFieldBase`

<Canvas>
  <Story id="components-componentlibrary-textfieldbase--disabled" />
</Canvas>

```jsx
import { TextFieldBase } from '../../component-library';

<TextFieldBase disabled />;
```

### Error

Use the `error` prop to set the error state of the `TextFieldBase`

<Canvas>
  <Story id="components-componentlibrary-textfieldbase--error-story" />
</Canvas>

```jsx
import { TextFieldBase } from '../../component-library';

<TextFieldBase error />;
```

### Max Length

Use the `maxLength` prop to set the maximum allowed input characters for the `TextFieldBase`

<Canvas>
  <Story id="components-componentlibrary-textfieldbase--max-length" />
</Canvas>

```jsx
import { TextFieldBase } from '../../component-library';

<TextFieldBase maxLength={10} />;
```

### Read Only

Use the `readOnly` prop to set the `TextFieldBase` to read only. When `readOnly` is true `TextFieldBase` will not have a focus state.

<Canvas>
  <Story id="components-componentlibrary-textfieldbase--read-only" />
</Canvas>

```jsx
import { TextFieldBase } from '../../component-library';

<TextFieldBase readOnly />;
```

### Required

Use the `required` prop to set the `TextFieldBase` to required. Currently there is no visual difference to the `TextFieldBase` when required.

<Canvas>
  <Story id="components-componentlibrary-textfieldbase--required" />
</Canvas>

```jsx
import { TextFieldBase } from '../../component-library';

// Currently no visual difference
<TextFieldBase required />;
```