# Label
> Component for labelling content with certain keywords, showing unread content, highlighting new content and displaying status.

## Import

```js
import { Label, LabelDot } from '@gemini-suite/vera-react';
```

## Examples

### Sizes

`Label` comes in two sizes: `medium` and `small`. By default, it uses `medium` size.

```jsx
<Flex gap="spacingS" wrap="wrap">
  <Label color="accent" size="medium">
    Medium
  </Label>
  <Label color="accent" size="small">
    Small
  </Label>
</Flex>
```

### Colors

Label can be used to communicate an object's status or attribute, and thus support multiple color schemes.
Vera's standard palettes are available via the `color` prop.

```jsx
<Flex gap="spacingS" wrap="wrap">
  <Label>Label</Label>
  <Label color="accent">Label</Label>
  <Label color="success">Label</Label>
  <Label color="danger">Label</Label>
  <Label color="warning">Label</Label>
  <Label color="info">Label</Label>
</Flex>
```

### Variants

Each color can be used with its default (`strong`) appearance or with `subtle` and `outline` variants.

Subtle and outline labels have more minimal appearance and can be used to avoid visual overload.

```jsx
<Flex flow="column" gap="spacingM">
  <Flex gap="spacingS" wrap="wrap">
    <Label variant="strong">Label</Label>
    <Label variant="strong" color="accent">
      Label
    </Label>
    <Label variant="strong" color="success">
      Label
    </Label>
    <Label variant="strong" color="danger">
      Label
    </Label>
    <Label variant="strong" color="warning">
      Label
    </Label>
    <Label variant="strong" color="info">
      Label
    </Label>
  </Flex>
  <Flex gap="spacingS" wrap="wrap">
    <Label variant="subtle">Label</Label>
    <Label variant="subtle" color="accent">
      Label
    </Label>
    <Label variant="subtle" color="success">
      Label
    </Label>
    <Label variant="subtle" color="danger">
      Label
    </Label>
    <Label variant="subtle" color="warning">
      Label
    </Label>
    <Label variant="subtle" color="info">
      Label
    </Label>
  </Flex>
  <Flex gap="spacingS" wrap="wrap">
    <Label variant="outline">Label</Label>
    <Label variant="outline" color="accent">
      Label
    </Label>
    <Label variant="outline" color="success">
      Label
    </Label>
    <Label variant="outline" color="danger">
      Label
    </Label>
    <Label variant="outline" color="warning">
      Label
    </Label>
    <Label variant="outline" color="info">
      Label
    </Label>
  </Flex>
</Flex>
```

### With icons

`Label` can be decorated with supporting icons using `startElement` and `endElement` props.

```jsx
<Flex gap="spacingS" wrap="wrap">
  <Label
    variant="outline"
    color="accent"
    startElement={<SvgIcon iconName="heart" />}
  >
    Favorite pick
  </Label>
  <Label
    variant="subtle"
    color="warning"
    startElement={<SvgIcon iconName="warning" />}
  >
    Attention needed
  </Label>
  <Label
    variant="strong"
    color="success"
    endElement={<SvgIcon iconName="check" />}
  >
    Task completed
  </Label>
  <Label
    variant="subtle"
    color="success"
    startElement={<SvgIcon iconName="arrowUp" />}
  >
    {'20%'}
  </Label>
  <Label
    variant="subtle"
    color="danger"
    startElement={<SvgIcon iconName="arrowDown" />}
  >
    {'12%'}
  </Label>
</Flex>
```

### With dots

`Label` can be decorated with dot indicator by passing `LabelDot` to `startElement` prop.

<Callout variant="tip">

`LabelDot` composes [Hint Dot component](/components/hint-dot).

</Callout>

```jsx
<Flex flow="column">
  <Flex gap="spacingS" wrap="wrap">
    <Label variant="subtle" color="accent" startElement={<LabelDot />}>
      Label
    </Label>
    <Label variant="subtle" color="success" startElement={<LabelDot />}>
      Label
    </Label>
    <Label variant="subtle" color="danger" startElement={<LabelDot />}>
      Label
    </Label>
    <Label variant="subtle" color="warning" startElement={<LabelDot />}>
      Label
    </Label>
    <Label variant="subtle" color="info" startElement={<LabelDot />}>
      Label
    </Label>
  </Flex>
  <Flex gap="spacingS" wrap="wrap">
    <Label variant="outline" startElement={<LabelDot color="dataPurple80" />}>
      Label
    </Label>
    <Label variant="outline" startElement={<LabelDot color="dataOrange80" />}>
      Label
    </Label>
    <Label variant="outline" startElement={<LabelDot color="dataLazuli80" />}>
      Label
    </Label>
    <Label variant="outline" startElement={<LabelDot color="dataPear80" />}>
      Label
    </Label>
    <Label variant="outline" startElement={<LabelDot color="dataLime80" />}>
      Label
    </Label>
  </Flex>
</Flex>
```

### Shape

Each label type can be circular.

```jsx
<Flex gap="spacingS">
  <Label circular color="accent">
    Label
  </Label>
  <Label circular variant="subtle">
    Label
  </Label>
  <Label circular variant="outline" startElement={<SvgIcon iconName="time" />}>
    Label
  </Label>
  <Label circular variant="subtle" color="success" startElement={<LabelDot />}>
    Label
  </Label>
</Flex>
```

Circular labels are typically used for counts:

```jsx
<Flex gap="spacingS">
  <Label circular color="success">
    10
  </Label>
  <Label circular variant="outline" color="danger">
    2
  </Label>
  <Label circular color="danger" size="small">
    543
  </Label>
  <Label circular variant="outline" color="info" size="small">
    615
  </Label>
</Flex>
```

### Removable label

A label can be used as a tag with close button. Use `onRemove` property to make label removable.

```jsx
() => {
  const [colors, setColors] = React.useState(['Danger', 'Success', 'Info']);

  return (
    <Flex flow="column">
      <Flex gap="spacingS">
        {colors.map(color => (
          <Label
            key={color}
            color={color.toLowerCase()}
            onRemove={() =>
              setColors(old => old.filter(state => state !== color))
            }
          >
            {color}
          </Label>
        ))}
      </Flex>
    </Flex>
  );
};
```

### Custom theming

For non-standard use cases, `Label` supports theming via `css` prop which gives you access to [any color token](/tokens/colors):

```jsx
<Flex gap="spacingS" wrap="wrap">
  <Label
    css={{
      color: '$foregroundInverse',
      backgroundColor: '$backgroundNeutralStrong'
    }}
  >
    Label
  </Label>
  <Label
    css={{
      color: '$colorWhite',
      backgroundColor: '$dataPurple100'
    }}
  >
    Label
  </Label>
</Flex>
```

### Possible applications

Labels can be used within block lists, buttons, headings and more:

```jsx
<Flex flow="column" cross="start">
  <Heading as="h2">
    Heading
    <Text fontFamily="base" marginLeft="spacingS">
      <Label color="info" size="small" className="vaM">
        New
      </Label>
    </Text>
  </Heading>

  <Button>
    {'Button'}
    <Label
      className="mLs"
      variant="subtle"
      color="accent"
      circular
      size="small"
    >
      2
    </Label>
  </Button>

  <Grid
    columns="3"
    className="bdrAs roundedAs bdr-neutral--subtle pAxl elevationS"
  >
    <Box>Squirrel</Box>
    <Label color="success" variant="subtle">
      Mammal
    </Label>
    <GridItem>
      <Label circular>0</Label>
    </GridItem>
    <Box>Koala</Box>
    <Label color="success" variant="subtle">
      Mammal
    </Label>
    <GridItem>
      <Label circular color="warning">
        8
      </Label>
    </GridItem>
    <Box>Dove</Box>
    <Label color="info" variant="subtle" css={{ width: 'max-content' }}>
      Bird
    </Label>
    <GridItem>
      <Label circular color="danger">
        25
      </Label>
    </GridItem>
  </Grid>

  <Flex flow="column" gap="spacingS" cross="start">
    <h4>Filters</h4>
    <Flex gap="spacingS">
      <Label color="accent" onRemove={() => {}}>
        {'4WD'}
      </Label>
      <Label color="accent" onRemove={() => {}}>
        {'Undamaged'}
      </Label>
      <Label color="accent" onRemove={() => {}}>
        {'< 50km'}
      </Label>
      <Label color="accent" onRemove={() => {}}>
        {'Black, red'}
      </Label>
    </Flex>
  </Flex>
</Flex>
```

With help of [Anchor component](/components/layout/anchor) you can attach `Label` to a corner of an element:

```jsx
<Flex>
  <Anchor.Root>
    <Avatar.Root of="Fritjof">
      <Avatar.Initials />
    </Avatar.Root>
    <Anchor.Target
      inset="14%"
      as={Label}
      color="danger"
      circular
      size="small"
      showOutlineRing
    >
      {'5'}
    </Anchor.Target>
  </Anchor.Root>
  <Anchor.Root>
    <Avatar.Root of="Torvald Halvor">
      <Avatar.Image src="https://images.unsplash.com/photo-1552058544-f2b08422138a?ixlib=rb-1.2.1&amp;q=80&amp;fm=jpg&amp;crop=faces&amp;fit=crop&amp;h=200&amp;w=200&amp;ixid=eyJhcHBfaWQiOjE3Nzg0fQ" />
      <Avatar.Fallback>
        <Avatar.Initials />
      </Avatar.Fallback>
    </Avatar.Root>
    <Anchor.Target
      position="bottom-end"
      inset="14%"
      as={Label}
      color="success"
      circular
      size="small"
      showOutlineRing
    >
      <SvgIcon iconName="check" />
    </Anchor.Target>
  </Anchor.Root>
  <Anchor.Root>
    <Button variant="outline" withLoneIcon aria-label="3 filters active">
      <SvgIcon iconName="filter" />
    </Button>
    <Anchor.Target
      inset="$sizes$2"
      as={Label}
      color="info"
      circular
      size="small"
    >
      {'3'}
    </Anchor.Target>
  </Anchor.Root>
  <Anchor.Root>
    <Button
      variant="outline"
      withLoneIcon
      aria-label="More than 99 unread messages"
    >
      <SvgIcon iconName="mail" />
    </Button>
    <Anchor.Target
      inset="$sizes$2"
      as={Label}
      color="info"
      circular
      size="small"
    >
      {'99+'}
    </Anchor.Target>
  </Anchor.Root>
</Flex>
```

---

## API Reference

### Label

| Name              | Type                                                                    | Default     | Description                                                                                                                                                                                                                                                                                  | Required |
| ----------------- | ----------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`              | `keyof JSX.IntrinsicElements \| React.ComponentType<any>`               | `span`      | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css`             | `StitchesCss`                                                           |             | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants.                                                 |          |
| `color`           | `"neutral" \| "accent" \| "success" \| "danger" \| "info" \| "warning"` | `"neutral"` | The color of the label.                                                                                                                                                                                                                                                                      |          |
| `variant`         | `"strong" \| "subtle" \| "outline"`                                     | `"strong"`  | Visual variant of the label.                                                                                                                                                                                                                                                                 |          |
| `circular`        | `boolean`                                                               |             | When `true`, label has circular corners.                                                                                                                                                                                                                                                     |          |
| `size`            | `"small" \| "medium"`                                                   | `medium`    | The size of the label.                                                                                                                                                                                                                                                                       |          |
| `startElement`    | `React.ReactElement`                                                    |             | `ReactElement` to render to the left of the label's children.                                                                                                                                                                                                                                |          |
| `endElement`      | `React.ReactElement`                                                    |             | `ReactElement` to render to the right of the label's children.                                                                                                                                                                                                                               |          |
| `isDisabled`      | `boolean`                                                               |             | When `true`, the label will be disabled,                                                                                                                                                                                                                                                     |          |
| `onRemove`        | `(event: React.MouseEvent<HTMLButtonElement>) => void`                  |             | If present, label has button with close icon. Callback passed to \`onRemove\` is invoked when removal button is clicked.                                                                                                                                                                     |          |
| `showOutlineRing` | `boolean`                                                               |             | When `true`, an outline ring around the label is shown. This is useful for a cut-out effect when placing the label over other element.                                                                                                                                                       |          |
| `margin`          | `SpacingToken`                                                          |             | Sets `margin` to one of the corresponding [spacing tokens](/tokens/white-space).                                                                                                                                                                                                             |          |
| `marginX`         | `SpacingToken`                                                          |             | Sets `margin-left` and `margin-right` to one of the corresponding [spacing tokens](/tokens/white-space).                                                                                                                                                                                     |          |
| `marginY`         | `SpacingToken`                                                          |             | Sets `margin-top` and `margin-bottom` to one of the corresponding [spacing tokens](/tokens/white-space).                                                                                                                                                                                     |          |
| `marginBottom`    | `SpacingToken`                                                          |             | Sets `margin-bottom` to one of the corresponding [spacing tokens](/tokens/white-space).                                                                                                                                                                                                      |          |
| `marginLeft`      | `SpacingToken`                                                          |             | Sets `margin-left` to one of the corresponding [spacing tokens](/tokens/white-space).                                                                                                                                                                                                        |          |
| `marginRight`     | `SpacingToken`                                                          |             | Sets `margin-right` to one of the corresponding [spacing tokens](/tokens/white-space).                                                                                                                                                                                                       |          |
| `marginTop`       | `SpacingToken`                                                          |             | Sets `margin-top` to one of the corresponding [spacing tokens](/tokens/white-space).                                                                                                                                                                                                         |          |

### LabelDot

| Name    | Type          | Default | Description                                                                                                                                                                                                                                  | Required |
| ------- | ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css`   | `StitchesCss` |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants. |          |
| `color` | `ColorToken`  |         | The color of the dot. Foreground, core and data visualisation values from [color tokens](/tokens/colors) are available.                                                                                                                      |          |