@commercetools-uikit/field-label
Version:
The FieldLabel component represents the label for a field in a form.
113 lines (84 loc) • 8.13 kB
Markdown
<!-- 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).