# Hint Dot
> A decorative indicator to either call attention to an item or highlight it's status.

## Import

```js
import { HintDot } from '@gemini-suite/vera-react';
```

## Examples

### Basic

`HintDot` is just a small decorative indicator often used as a more compact alternative for a [Label](/components/label).
It can be used to point out that something has changed or grab user's attention without giving a count.

```jsx
<Flex gap="spacingXs">
  Inbox <HintDot tone="info" aria-label="Contains unread email" />
</Flex>
```

### Sizes

By default `HintDot` will inherit its size from the parent element's text size.
Use `size` prop to pick one of the predefined sizes: `medium` and `small`.

```jsx
<Flex gap="spacingS" flow="column">
  <Flex gap="spacingXs">
    <HintDot tone="info" size="medium" />
    <Text>Medium</Text>
  </Flex>
  <Flex gap="spacingXs">
    <HintDot tone="info" size="small" />
    <Text variant="zeta">Small</Text>
  </Flex>
</Flex>
```

### Tone

Use the `tone` property to indicate the intent. Default tones correspond with [functional color tokens](/tokens/colors#functional-tokens) roles.

```jsx
<Flex gap="spacingS">
  <HintDot />
  <HintDot tone="accent" />
  <HintDot tone="info" />
  <HintDot tone="success" />
  <HintDot tone="danger" />
  <HintDot tone="warning" />
</Flex>
```

### Placement

`HintDot` is typically placed on the trailing end of icons, components or text.

```jsx
<Tabs.Root defaultValue="tab2">
  <Flex flow="column">
    <Tabs.List withDivider={false}>
      <Tabs.Trigger value="tab1">
        <Flex gap="spacingXs">
          <Tabs.TriggerLabel>{'First'}</Tabs.TriggerLabel>
          <HintDot tone="accent" aria-label="New content available" />
        </Flex>
      </Tabs.Trigger>
      <Tabs.Trigger value="tab2">{'Second'}</Tabs.Trigger>
    </Tabs.List>
    <Tabs.Content value="tab1">{"I'm first tab."}</Tabs.Content>
    <Tabs.Content value="tab2">{"I'm second tab."}</Tabs.Content>
  </Flex>
</Tabs.Root>
```

With help of [Anchor component](/components/layout/anchor) you can attach `HintDot` to a corner of an element to indicate the status of that element.

```jsx
<Flex>
  <Anchor.Root>
    <Avatar.Root of="Liv Margareta">
      <Avatar.Initials />
    </Avatar.Root>
    <Anchor.Target
      inset="14%"
      as={HintDot}
      showOutlineRing
      tone="success"
      role="status"
      aria-label="Active"
    />
  </Anchor.Root>
  <Tooltip delay={300} content="You have 5 unread messages">
    <Button variant="outline" withLoneIcon>
      <Anchor.Root>
        <SvgIcon iconName="mail" />
        <Anchor.Target as={HintDot} showOutlineRing tone="info" />
      </Anchor.Root>
    </Button>
  </Tooltip>
  <Button variant="outline" withLoneIcon aria-label="3 filters active">
    <Anchor.Root>
      <SvgIcon iconName="filter" />
      <Anchor.Target as={HintDot} showOutlineRing tone="info" />
    </Anchor.Root>
  </Button>
  <Anchor.Root>
    <Label variant="subtle">New version</Label>
    <Anchor.Target as={HintDot} showOutlineRing tone="info" />
  </Anchor.Root>
</Flex>
```

### Accessible label

When the intent isn't provided by accompanying text, it's highly recommended to provide an `aria-label` for assistive tech users.

```jsx
<button type="button">
  <Flex gap="spacingXs">
    <Text>Action item</Text>
    <HintDot tone="danger" aria-label="Contains issues" />
  </Flex>
</button>
```

### Cut-out effect

When `HintDot` is overlapping with other element, you can simulate a cut-out effect with an outline ring by using the `showOutlineRing` property.

```jsx
<Anchor.Root>
  <Avatar.Root of="Fritjof Snorre">
    <Avatar.Image src="https://images.unsplash.com/photo-1548946526-f69e2424cf45?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={HintDot}
    showOutlineRing
    tone="warning"
    role="status"
    aria-label="Busy"
  />
</Anchor.Root>
```

### Custom tone

You can provide a custom tone by using `tone="custom"` property and setting the `color` property to one of the [color tokens](/tokens/colors).

```jsx
<Flex gap="spacingS">
  <HintDot tone="custom" color="dataPurple80" />
  <HintDot tone="custom" color="dataOrange80" />
  <HintDot tone="custom" color="dataLazuli80" />
</Flex>
```

### Status list

`HintDot` enables creating statuses tailored to your app's need.

```jsx
<Flex flow="column">
  <Flex flow="column" gap="spacingXs">
    <Flex gap="spacingXs">
      <HintDot tone="custom" color="transparent" outlined /> Inactive
    </Flex>
    <Flex gap="spacingXs">
      <HintDot tone="custom" color="foregroundNeutralMinimal" /> Pending
    </Flex>
    <Flex gap="spacingXs">
      <HintDot tone="warning" /> In progress
    </Flex>
    <Flex gap="spacingXs">
      <HintDot tone="accent" /> Active
    </Flex>
    <Flex gap="spacingXs">
      <HintDot tone="danger" /> Error
    </Flex>
  </Flex>
  <Flex flow="column" gap="spacingXs">
    <Flex gap="spacingXs">
      <HintDot tone="custom" color="transparent" outlined /> Cancelled
    </Flex>
    <Flex gap="spacingXs">
      <HintDot tone="warning" /> Pending
    </Flex>
    <Flex gap="spacingXs">
      <HintDot tone="danger" /> Error
    </Flex>
    <Flex gap="spacingXs">
      <HintDot tone="success" /> Success
    </Flex>
  </Flex>
</Flex>
```

### On dark background

When using dot indicator on a dark background, it can be given a thin outline border for better constrast by setting the `outline` property to `true`

```jsx
<Flex
  flow="column"
  gap="spacingXs"
  padding="spacingM"
  css={{
    backgroundColor: '$backgroundNeutralContrast',
    color: '$foregroundInverse'
  }}
>
  <Flex gap="spacingXs">
    <HintDot tone="custom" color="transparent" outlined /> Disconnected
  </Flex>
  <Flex gap="spacingXs">
    <HintDot tone="custom" color="foregroundNeutralMinimal" outlined />
    Connecting…
  </Flex>
  <Flex gap="spacingXs">
    <HintDot tone="accent" outlined /> Connected
  </Flex>
</Flex>
```

### App header status

```jsx
<AppHeader.Root>
  <AppHeader.Logo />
  <AppHeader.Title>{'Product name'}</AppHeader.Title>
  <AppHeader.Status>
    <Flex gap="spacingXs">
      <HintDot tone="accent" outlined />
      {'Connected'}
    </Flex>
  </AppHeader.Status>
  <AppHeader.ActionList aria-label="AppHeader actions">
    <Tooltip content="Settings" delay={300}>
      <AppHeader.ActionListItem>
        <SvgIcon iconName="settings" />
      </AppHeader.ActionListItem>
    </Tooltip>
    <Tooltip content="Notifications" delay={300}>
      <AppHeader.ActionListItem>
        <SvgIcon iconName="bell" />
      </AppHeader.ActionListItem>
    </Tooltip>
    <Menu.Root>
      <Menu.Trigger as={AppHeader.ActionListItem}>
        <Avatar.Root of={'Max Mustermann'}>
          <Avatar.Initials color="accentSubtle" />
        </Avatar.Root>
      </Menu.Trigger>
      <Menu.Content placement={Placement.BOTTOM_RIGHT}>
        <Flex paddingY="spacingS" paddingX="spacingM">
          <Avatar.Root of={'Max Mustermann'}>
            <Avatar.Initials color="accentSubtle" />
          </Avatar.Root>
          <Box>
            {'Max Mustermann'}
            <Text as="div" variant="zeta" color="foregroundNeutralSubtle">
              {'max.mustermann@invera-tech.com'}
            </Text>
          </Box>
        </Flex>
        <Menu.Separator />
        <Menu.Item startElement={<SvgIcon iconName="mobile" />}>
          {'Activate MFA'}
        </Menu.Item>
        <Menu.Separator />
        <Menu.Item intent="danger">{'Log Out'}</Menu.Item>
      </Menu.Content>
    </Menu.Root>
  </AppHeader.ActionList>
</AppHeader.Root>
```

---

## API Reference

| 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.                                                 |          |
| `tone`            | `"neutral" \| "accent" \| "warning" \| "info" \| "success" \| "danger" \| "custom"` | `"neutral"` | The tone of the indicator.                                                                                                                                                                                                                                                                   |          |
| `outlined`        | `boolean`                                                                           |             | When `true`, the indicator has thin outline border for better contrast against background.                                                                                                                                                                                                   |          |
| `showOutlineRing` | `boolean`                                                                           | `false`     | When `true`, an outline ring around the indicator is shown. This is useful for a cut-out effect when placing the indicator over other element.                                                                                                                                               |          |
| `color`           | `ColorToken`                                                                        |             | The color of the indicator when `tone` is set to `custom`. Foreground, core and data visualisation values from [color tokens](/tokens/colors) are available.                                                                                                                                 |          |
| `size`            | `"small" \| "medium"`                                                               |             | The size of the indicator.                                                                                                                                                                                                                                                                   |          |