<!-- THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. -->
<!-- This file is created by the `yarn generate-readme` script. -->

# FieldLabel

## Description

The FieldLabel component represents the label for a field in a form. This component can also be used to better explain an input field and to guide the user to fill a form.

## Installation

```
yarn add @commercetools-uikit/field-label
```

```
npm --save install @commercetools-uikit/field-label
```

Additionally install the peer dependencies (if not present)

```
yarn add react
```

```
npm --save install react
```

## Usage

```jsx
import { defineMessage, FormattedMessage } from 'react-intl';
import FlatButton from '@commercetools-uikit/flat-button';
import FieldLabel from '@commercetools-uikit/field-label';
import { WarningIcon } from '@commercetools-uikit/icons';

const messages = defineMessage();

const Example = () => (
  <FieldLabel
    title={<FormattedMessage {...messages.title} />}
    hasRequiredIndicator={true}
    onInfoButtonClick={() => {}}
    hint={<FormattedMessage {...messages.hint} />}
    hintIcon={<WarningIcon />}
    description={<FormattedMessage {...messages.description} />}
    badge={<FlatButton tone="primary" label="show" />}
    htmlFor="sampleInput"
    horizontalConstraint={7}
  />
);

export default Example;
```

## Properties

| Props                  | Type                                                                                                  | Required | Default   | Description                                                                                                                                                                                                                                                       |
| ---------------------- | ----------------------------------------------------------------------------------------------------- | :------: | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`                | `union`<br/>Possible values:<br/>`string , ReactNode`                                                 |    ✅    |           | Title of the label                                                                                                                                                                                                                                                |
| `hint`                 | `union`<br/>Possible values:<br/>`string , ReactNode`                                                 |          |           | Hint for the label. Provides a supplementary but important information regarding the behaviour of the input (e.g warn about uniqueness of a field, when it can only be set once), whereas description can describe it in more depth. Can also receive a hintIcon. |
| `description`          | `union`<br/>Possible values:<br/>`string , ReactNode`                                                 |          |           | Provides a description for the title.                                                                                                                                                                                                                             |
| `onInfoButtonClick`    | `Function`<br/>[See signature.](#signature-oninfobuttonclick)                                         |          |           | Function called when info button is pressed. Info button will only be visible when this prop is passed.                                                                                                                                                           |
| `tone`                 | `union`<br/>Possible values:<br/>`'primary' , 'inverted'`                                             |          |           | Indicates the tone to be applied to the label                                                                                                                                                                                                                     |
| `hintIcon`             | `ReactElement`                                                                                        |          |           | Icon to be displayed beside the hint text. Will only get rendered when hint is passed as well.                                                                                                                                                                    |
| `badge`                | `ReactNode`                                                                                           |          |           | Badge to be displayed beside the label. Might be used to display additional information about the content of the field (E.g verified email)                                                                                                                       |
| `hasRequiredIndicator` | `boolean`                                                                                             |          |           | Indicates if the labeled field is required in a form                                                                                                                                                                                                              |
| `htmlFor`              | `string`                                                                                              |          |           | The for HTML attribute, used to reference form elements with the related attribute id or aria-labelledby.                                                                                                                                                         |
| `id`                   | `string`                                                                                              |          |           | The id HTML attribute, used to reference non-form elements with the related attribute aria-labelledby.                                                                                                                                                            |
| `horizontalConstraint` | `union`<br/>Possible values:<br/>`, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 'scale', 'auto'` |          | `'scale'` | Horizontal size limit of the label.                                                                                                                                                                                                                               |

## Signatures

### Signature `onInfoButtonClick`

```ts
(
  event: MouseEvent<HTMLButtonElement> | KeyboardEvent<HTMLButtonElement>
) => void
```

## `hintIcon`

The `hintIcon` also accepts a custom `color` while defaulting to `warning` in the case above. The `hintIcon` does **not** support the `size` prop, and will always be rendered in the size `medium`.

```diff
<FieldLabel
  title={<FormattedMessage {...messages.title} />}
  hasRequiredIndicator={true}
  onInfoButtonClick={() => {}} />}
  hint={<FormattedMessage {...messages.hint} />}
- hintIcon={<WarningIcon />}
+ hintIcon={<WarningIcon color="primary" />}
  description={<FormattedMessage {...messages.description} />}
  badge={<FlatButton tone="primary" label="show" />}
  htmlFor="sampleInput"
  horizontalConstraint={7}
/>
```

## `hint` vs `description`

Most fields will only use the `description` which provides more information about what the entered value will be used for.

The `hint` however is used to show additional information about the value the user enters. It can show the allowed characters. It can also show whether the entered value has errors (like a reference no longer existing in an attribute) when the form is loaded for the first time.

Neither of them should be used for form validation.

## Dos and don'ts

Recommended to be used in vertical forms. (E.g input field below the label, and not besides).