# Story Header

> A floating glass bar for a long, chaptered page. It names the chapter you are reading and fills a line as you scroll.

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

export default function StoryHeaderDemo() {
  // The transform keeps the fixed header inside this frame instead of the docs page.
  return (
    <div style={{ position: 'relative', width: '100%', height: 260, overflow: 'hidden', transform: 'translateZ(0)', background: `url(${cup.src}) center / cover` }}>
      <StoryHeader
        brand={<a href="#">Still</a>}
        items={[
          { label: 'Coffee', href: '#coffee' },
          { label: 'Brew guides', href: '#guides' },
        ]}
        current={{ label: 'The pour', href: '#pour', marker: 'II' }}
        actions={<ActionLink href="#visit" shape="pill">Visit</ActionLink>}
      />
    </div>
  );
}
```

## 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, StoryHeader } from '@brand-studio/ui';
import brand from './brand.json';

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

## Usage

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

```tsx
<StoryHeader
  brand={<a href="/">Still</a>}
  items={[{ label: 'Coffee', href: '/coffee' }]}
  current={{ label: 'The pour', href: '#pour', marker: 'II' }}
  actions={<ActionLink href="/visit" shape="pill">Visit</ActionLink>}
/>
```

The bar is fixed to the top of the window, so the page's first section should start under it. Update `current` as the reader moves between chapters, for example from an `IntersectionObserver`.

## Accessibility

- Built on Header: a `<header>` with a labelled `<nav>`, and a Mobile Navigation button when the bar is narrower than 40rem.
- The current chapter is a link back to that chapter's heading. It hides when the bar is narrower than 56rem.
- The scroll line is decoration. Browsers without scroll-driven animation leave it out.

## API Reference

| Prop | Type | Default |
|---|---|---|
| `brand` | `React.ReactNode` | – |
| `items?` | `NavLink[]` | – |
| `current?` | `{ label: React.ReactNode; href: string; marker?: React.ReactNode; }` | – |
| `actions?` | `React.ReactNode` | – |
| `label?` | `string` | `'Main'` |
| `className?` | `string` | `''` |

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