# Story Hero

> The opening frame of a page: headline, promise, action and image.

```tsx
import { ActionLink, StoryHero } from '@brand-studio/ui';
import { cup } from '@/demos/assets';

export default function StoryHeroDemo() {
  return (
    <StoryHero
      eyebrow="Still Coffee"
      title="Make room for the first sip."
      description="Still is a fictional coffee brand from the Brand Studio showcase."
      asset={cup}
      action={<ActionLink href="#menu">See the menu</ActionLink>}
    />
  );
}
```

## Installation

```sh
npm install @brand-studio/ui
```

React 18 or 19 is a peer dependency. Import the stylesheet once and wrap the app in a brand theme:

```tsx
import '@brand-studio/ui/styles.css';
import { BrandTheme, StoryHero } from '@brand-studio/ui';
import brand from './brand.json';

<BrandTheme palette={brand.tokens} mode="system">
  {/* your app */}
</BrandTheme>
```

## Usage

```tsx
import { StoryHero } from '@brand-studio/ui';
```

```tsx
<StoryHero
  title="Make room for the first sip."
  description="…"
  asset={cup}
  action={<ActionLink href="/menu">See the menu</ActionLink>}
/>
```

## Examples

### Overlay

The copy sits on a scrim that stays readable before the image loads.

```tsx
import { ActionLink, StoryHero } from '@brand-studio/ui';
import { pour } from '@/demos/assets';

export default function StoryHeroOverlay() {
  return (
    <StoryHero
      variant="overlay"
      title="Give it a moment."
      description="The copy sits on a scrim, so it stays readable before the image loads."
      asset={pour}
      action={<ActionLink href="#visit" tone="inverse">Plan a visit</ActionLink>}
    />
  );
}
```

## Accessibility

- Renders the page `<h1>`. Use one StoryHero per page.
- The image loads with high priority.

## API Reference

| Prop | Type | Default |
|---|---|---|
| `title` | `React.ReactNode` | – |
| `description` | `string` | – |
| `asset` | `ImageAsset` | – |
| `action` | `React.ReactNode` | – |
| `eyebrow?` | `string` | – |
| `id?` | `string` | – |
| `variant?` | `"overlay" \| "split"` | `'split'` |

Source: https://brandstudio.js.org/docs/components/story-hero/
