# OverlapStack

```tsx
import { OverlapStack } from '@tangible/ui';
```

Interactive docs and examples: [OverlapStack in Storybook](https://storybook-tangible-ui.pages.dev/?path=/docs/components-overlapstack--docs).

## OverlapStack props

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `ReactNode` | | Children to stack |
| `aria-label?` | `string` | | Accessible label for the stack group. Adds role="group" when provided. |
| `aria-labelledby?` | `string` | | ID of element labelling the stack. Adds role="group" when provided. |
| `className?` | `string` | | Additional class name |
| `frame?` | `boolean` | | Enable clipping frame on item wrappers. Adds border-radius and overflow:hidden. Customise via tokens: `--tui-overlap-stack-item-radius` (default: full); `--tui-overlap-stack-border-width` (default: 0); `--tui-overlap-stack-border-color` (default: bg-surface) |
| `max?` | `number` | | Maximum visible items. Overflow becomes +N badge. |
| `overflowLabel?` | `(count: number) => string` | `` (count) => `${count} more` `` | Accessible label for the overflow badge. For i18n support. Function receives count and returns label string. |
| `overlap?` | `number \| string` | | Overlap amount in pixels (negative) or CSS length string. |
| `renderOverflow?` | `(count: number) => ReactNode` | | Custom renderer for overflow badge. Receives count of hidden items. |
| `style?` | `React.CSSProperties` | | Inline styles |

### OverlapStack.Overflow

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `ReactNode` | | |
| `aria-label?` | `string` | | Accessible label for overflow badge |
| `className?` | `string` | | |
| `style?` | `React.CSSProperties` | | |

## Examples

- [Basic](https://storybook-tangible-ui.pages.dev/?path=/story/components-overlapstack--basic): Basic overlap stack with avatars. First avatar appears on top.

- [With Overflow](https://storybook-tangible-ui.pages.dev/?path=/story/components-overlapstack--with-overflow): With max limit — default overflow badge appears automatically.

- [Tight Overlap](https://storybook-tangible-ui.pages.dev/?path=/story/components-overlapstack--tight-overlap): Tighter overlap for smaller items.

- [Custom Overflow](https://storybook-tangible-ui.pages.dev/?path=/story/components-overlapstack--custom-overflow): Custom styled overflow badge using the `OverlapStack.Overflow` compound.
  This is the recommended pattern for custom overflow rendering.

- [Framed](https://storybook-tangible-ui.pages.dev/?path=/story/components-overlapstack--framed): Frame mode adds clipping and optional border ring.
  Use with raw images or elements that need uniform shape.

- [Framed With Border](https://storybook-tangible-ui.pages.dev/?path=/story/components-overlapstack--framed-with-border): Framed with border ring enabled via token.
  Border only applies when `frame` is true.

- [Arbitrary Children](https://storybook-tangible-ui.pages.dev/?path=/story/components-overlapstack--arbitrary-children): Works with any children — here using colored circles.
  Without `frame`, children render with their native styling.

- [Localised](https://storybook-tangible-ui.pages.dev/?path=/story/components-overlapstack--localised): Localised — every announced string is customisable. The stack itself is
  named via `aria-label` (which adds `role="group"`), and the automatic
  overflow badge announces via `overflowLabel`, rendered as `role="img"`
  so "+3" reads as "3 weitere Mitglieder" instead of "plus three".

- [Square Framed](https://storybook-tangible-ui.pages.dev/?path=/story/components-overlapstack--square-framed): Square items — `frame` with custom radius token.
  Demonstrates framing non-circular content.

## Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.

- `--tui-overlap-stack-overlap`
- `--tui-overlap-stack-overflow-bg`
- `--tui-overlap-stack-overflow-fg`
- `--tui-overlap-stack-item-radius`
- `--tui-overlap-stack-border-width`
- `--tui-overlap-stack-border-color`

---

Interactive version: https://storybook-tangible-ui.pages.dev/?path=/docs/components-overlapstack--docs