npm package: @highlight-ui/input
Description: Input UI component for the Personio UI Library
Author: Personio GmbH & Co. KG
Latest version: 6.1.8

[![npm](https://img.shields.io/npm/v/@highlight-ui/input)](https://www.npmjs.com/package/@highlight-ui/input)
[![personio.design](https://img.shields.io/static/v1?label=Personio&message=zeroheight&color=yellow)](https://www.personio.design/40d648a47/v/0/p/57b2c5-input-and-text-area/b/61d4aa)
[![storybook.personio.design](https://img.shields.io/static/v1?label=Personio&message=storybook&color=red)](https://storybook.personio.design/?path=/story/forms-and-input-input--default)

# @highlight-ui/input

## Installation

Using npm:

```bash
npm install @highlight-ui/input
```

Using yarn:

```bash
yarn add @highlight-ui/input
```

Using pnpm:

```bash
pnpm install @highlight-ui/input
```

In your (S)CSS file:

```scss
@import url('@highlight-ui/input');
```

Once the package is installed, you can import the library:

```ts
import { Input, TextArea } from '@highlight-ui/input';
```

## Performance Tips

The Input component depends on [imask.js](https://imask.js.org/), which is a
relatively heavy dependency. This component's package is tree shakeable, if you
do not need the input masking functionalities you can import the `TextInput`
component instead of the `Input` component.

```ts
import { TextInput } from '@highlight-ui/input';
```

If you only need the masking functionalities of the component, you can import
the `MaskedInput` component:

```ts
import { MaskedInput } from '@highlight-ui/input';
```

## Usage

```tsx
import React from 'react';
import { Input } from '@highlight-ui/input';

export default function InputExample() {
  return <Input name="map" color="input-critical" type="light" />;
}
```

## Props 📜

### Input

> The [InputProps](https://gitlab.personio-internal.de/personio/platform/highlight-ui/-/blob/master/packages/ui/input/src/Input.tsx#L7) extends the [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) types

| Prop             | Type                                                                                                                                       | Required | Default   | Description                                                                                                                                                                           |
| :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | :------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `disabled`       | `boolean`                                                                                                                                  | No       | `false`   | Disables the input element                                                                                                                                                            |
| `className`      | `string`                                                                                                                                   | No       |           | Sets a class name to the component's root element                                                                                                                                     |
| `inputClassName` | `string`                                                                                                                                   | No       |           | Allows providing a custom class name to the input element                                                                                                                             |
| `outline`        | `"default", "warning", "error"`                                                                                                            | No       | `default` | Sets the color of the input's border                                                                                                                                                  |
| `focused`        | `boolean`                                                                                                                                  | No       | `false`   | Focuses the underlying input element                                                                                                                                                  |
| `prefix`         | `React.ReactNode`                                                                                                                          | No       |           | Renders the passed element on the left side of the input                                                                                                                              |
| `prefixVariant`  | `"opaque", "transparent"`                                                                                                                  | No       |           | Applies the specified style to the prefix element's container                                                                                                                         |
| `suffix`         | `React.ReactNode`                                                                                                                          | No       |           | Renders the passed element on the right side of the input                                                                                                                             |
| `containerRef`   | `React.Ref<HTMLDivElement>`                                                                                                                | No       |           | Passes a ref to the input's container element                                                                                                                                         |
| `maskOptions`    | [`MaskOptions`](https://gitlab.personio-internal.de/personio/platform/highlight-ui/-/blob/master/packages/ui/input/src/imaskExports.ts#L3) | No       |           | Function which accepts locale and returns an [imaskjs](https://imask.js.org/guide.html) configuration object used for creating an IMask instance which will control the input element |
| `onMaskAccept`   | `(e: MaskEvent) => void`                                                                                                                   | No       |           | Sets a callback for when an event is fired on input changes allowed by the mask. This prop only works with `maskOptions` provided.                                                    |
| `onMaskComplete` | `(e: MaskEvent) => void`                                                                                                                   | No       |           | Sets a callback for when an event is fired on input completion defined by the mask. This prop only works with `maskOptions` provided.                                                 |

### TextArea

> The [TextArea](https://gitlab.personio-internal.de/personio/platform/highlight-ui/-/blob/master/packages/ui/input/src/TextArea.tsx#L11) extends the [HTMLTextAreaElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLTextAreaElement) types

| Prop           | Type                            | Required | Default   | Description                                   |
| :------------- | :------------------------------ | :------- | :-------- | :-------------------------------------------- |
| `disabled`     | `boolean`                       | No       | `false`   | Disables the text area element                |
| `outline`      | `"default", "warning", "error"` | No       | `default` | Sets the color of the text area's border      |
| `containerRef` | `React.Ref<HTMLDivElement>`     | No       |           | Passes a ref to the input's container element |

## Contributing 🖌️

Please visit [personio.design](https://www.personio.design/40d648a47/v/0/p/57b2c5-input-and-text-area/b/61d4aa) for usage guidelines and visual examples.

If you're interested in contributing, please visit our [contribution page](https://www.personio.design/40d648a47/v/0/p/138faf-about-the-process).