# Anchor
> A layout component used to position an element relative to the corner of another element.

## Import

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

Anchor is a compound component that consists of multiple parts:

- `Anchor.Root`: The wrapper _that_ acts as a reference point for `Anchor.Target`.
- `Anchor.Target`: The target element placed relative to the corner of the anchoring element.

## Examples

### Basic

`Anchor` simplifies positioning target element to one of the corners of anchoring element. This is useful for positioning notification labels, avatar statuses, and similar cases.

```jsx
<Anchor.Root>
  <ExampleBox>{'⚓︎'}</ExampleBox>
  <Anchor.Target as={Label} color="info" circular size="small">
    <SvgIcon iconName="check" />
  </Anchor.Target>
</Anchor.Root>
```

### Placement

By default, target element sits on the `top-end` corner of the anchor element that it's attached to.
Use the `position` property to move the target to any corner of the anchor.

<Callout variant="tip">

Rather than `left` and `right`, we use `start` and `end` values for horizontal positioning, since they are flow-relative and depend on the writing mode or direction.

</Callout>

```jsx
() => {
  const [position, setPosition] = React.useState('top-end');

  return (
    <Flex flow="column" gap="spacingXl">
      <FormField.Root as={Flex} flow="column">
        <FormField.Label as="span">Position</FormField.Label>
        <RadioGroup value={position} onChange={setPosition}>
          <ContentBlock max="measureNarrow" center={false} gutters="none">
            <AutoGrid gap="spacingXs" min="6rem" max="50%">
              <Radio.Root value="top-end">
                <Radio.Indicator />
                <Radio.Label>{'top-end'}</Radio.Label>
              </Radio.Root>
              <Radio.Root value="bottom-end">
                <Radio.Indicator />
                <Radio.Label>{'bottom-end'}</Radio.Label>
              </Radio.Root>
              <Radio.Root value="top-start">
                <Radio.Indicator />
                <Radio.Label>{'top-start'}</Radio.Label>
              </Radio.Root>
              <Radio.Root value="bottom-start">
                <Radio.Indicator />
                <Radio.Label>{'bottom-start'}</Radio.Label>
              </Radio.Root>
            </AutoGrid>
          </ContentBlock>
        </RadioGroup>
      </FormField.Root>
      <Box>
        <Anchor.Root>
          <ExampleBox>{'⚓︎'}</ExampleBox>
          <Anchor.Target
            as={Label}
            position={position}
            color="info"
            circular
            size="small"
          >
            <SvgIcon iconName="check" />
          </Anchor.Target>
        </Anchor.Root>
      </Box>
    </Flex>
  );
};
```

### Inset

Use the `inset` property to fine-tune the position of the target relative to the anchor element that it's attached to.

<Callout variant="tip">

Value of the `inset` property corresponds to the [inset CSS
property](https://developer.mozilla.org/en-US/docs/Web/CSS/inset-inline-start), so all CSS length values are possible as well as referencing spacing scale values.

</Callout>

If your anchor-wrapped element has a circular shape, the target won't cover the element's visible area by default. You can fix this by moving the target closer to the anchor center by modifying the `inset`.

```jsx
<Flex>
  <Anchor.Root>
    <Avatar.Root of="Liv Margareta">
      <Avatar.Initials />
    </Avatar.Root>
    <Anchor.Target
      inset="14%"
      as={HintDot}
      showOutlineRing
      tone="success"
      aria-label="Available"
    />
  </Anchor.Root>
  <Anchor.Root>
    <Avatar.Root of="Liv Margareta">
      <Avatar.Initials />
    </Avatar.Root>
    <Anchor.Target
      position="bottom-end"
      inset="14%"
      as={HintDot}
      showOutlineRing
      tone="warning"
      aria-label="Busy"
    />
  </Anchor.Root>
</Flex>
```

If your anchor-wrapped element is an icon, you can apply `inset` to nudge the target closer to the icon center.

```jsx
<Button variant="outline" withLoneIcon aria-label="5 notifications">
  <Anchor.Root>
    <SvgIcon iconName="bell" />
    <Anchor.Target
      inset="$sizes$2"
      as={HintDot}
      showOutlineRing
      tone="danger"
    />
  </Anchor.Root>
</Button>
```

If a requirement is to push the target further away from the icon, simply apply negative `inset`.

```jsx
<Anchor.Root>
  <SvgIcon iconName="bell" />
  <Anchor.Target inset="-40%" as={Label} size="small" circular color="danger">
    {'5'}
  </Anchor.Target>
</Anchor.Root>
```

---

## API Reference

### Anchor.Root

| 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.                                                 |          |

### Anchor.Target

| 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.                                                 |          |
| `position` | `"top-start" \| "top-end" \| "bottom-start" \| "bottom-end"` | `"top-end"` | Position relative to the corner of the anchoring element.                                                                                                                                                                                                                                    |          |
| `inset`    | `StitchesCss['insetInlineStart']`                            | `0`         | The inset from the corner of the anchoring element. Accepts any valid [CSS length value](https://developer.mozilla.org/en-US/docs/Web/CSS/length) .                                                                                                                                          |          |