# Scroll Header

A header that stays at the top as the page scrolls, and gains an edge once content passes under it.

Source: [scroll-header.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/scroll-header.tsx)

```tsx
"use client";

import { ChevronRightIcon } from "lucide-react";
import * as React from "react";

import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import { Card } from "@/components/ui/card";
import { ScrollArea } from "@/components/ui/scroll-area";
import { ScrollHeader, ScrollHeaderTitle } from "@/components/ui/scroll-header";

const milestones = [
  { title: "Usage-based billing in beta", owner: "Priya Raman", due: "Jul 28", status: "Shipped" },
  { title: "SSO on every paid plan", owner: "Leo Park", due: "Aug 15", status: "On track" },
  { title: "Audit log export to S3", owner: "Maya Chen", due: "Aug 29", status: "At risk" },
  { title: "Self-serve seat changes", owner: "Tom Weiss", due: "Sep 12", status: "On track" },
  { title: "Invoices in nine languages", owner: "Ana Souza", due: "Sep 26", status: "Not started" },
] as const;

const variants = {
  Shipped: "success",
  "On track": "info",
  "At risk": "warning",
  "Not started": "default",
} as const;

export default function ScrollHeaderDocument() {
  const heading = React.useRef<HTMLHeadingElement>(null);

  return (
    <Card className="h-96 w-full max-w-lg gap-0 py-0">
      <ScrollArea scrollFade={false} className="min-h-0 flex-1 rounded-[inherit]">
        <ScrollHeader className="flex h-12 items-center gap-1.5 px-4">
          <span className="shrink-0 text-sm text-muted-foreground">Projects</span>
          <ChevronRightIcon className="size-3.5 shrink-0 text-icon-muted" />
          <ScrollHeaderTitle watch={heading}>Q3 planning</ScrollHeaderTitle>
          <Button size="sm" className="ml-auto">
            Share
          </Button>
        </ScrollHeader>
        <div className="flex flex-col gap-4 px-4 pt-2 pb-6">
          <div>
            <h2 ref={heading} className="text-xl font-medium">
              Q3 planning
            </h2>
            <p className="text-sm text-faint">Updated 2h ago by Maya Chen</p>
          </div>
          <p className="text-muted-foreground">
            Billing is the loudest source of support tickets, and most come from teams that outgrew
            the plan they signed up on. This quarter, plan changes become self-serve and metered
            usage leaves beta.
          </p>
          <h3 className="font-medium">Milestones</h3>
          <ul className="flex flex-col divide-y-[0.5px] divide-border-muted">
            {milestones.map((milestone) => (
              <li key={milestone.title} className="flex items-center gap-3 py-2.5">
                <div className="min-w-0 flex-1">
                  <p className="truncate">{milestone.title}</p>
                  <p className="text-2xs text-faint">
                    {milestone.owner} · {milestone.due}
                  </p>
                </div>
                <Badge variant={variants[milestone.status]}>{milestone.status}</Badge>
              </li>
            ))}
          </ul>
          <h3 className="font-medium">Risks</h3>
          <p className="text-muted-foreground">
            The audit log export depends on the storage migration. If that slips past August 15,
            export goes to our own bucket first and S3 follows in Q4.
          </p>
          <p className="text-muted-foreground">
            Invoices in more languages need a vendor. There are two quotes, and we decide by the end
            of July.
          </p>
        </div>
      </ScrollArea>
    </Card>
  );
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/scroll-header
```

## Usage

```tsx
"use client";

import * as React from "react";

import { ScrollHeader, ScrollHeaderTitle } from "@/components/ui/scroll-header";

export function Document() {
  const heading = React.useRef<HTMLHeadingElement>(null);

  return (
    <div className="h-dvh overflow-y-auto">
      <ScrollHeader className="flex h-12 items-center px-4">
        <ScrollHeaderTitle watch={heading}>Q3 planning</ScrollHeaderTitle>
      </ScrollHeader>
      <h1 ref={heading}>Q3 planning</h1>
    </div>
  );
}
```

`ScrollHeader` sticks to the top of the nearest scrolling container, or of the page, or of the
container given as `root`. It's transparent at rest, so it sits on the page like any other header.
Once the content after it scrolls beneath it, it gains a translucent surface and a hairline, and
has `data-scrolled`. The surface is the theme's `surface` color: the page's, or, inside a
[Card](https://ui.jarv.is/components/card.md), [Dialog](https://ui.jarv.is/components/dialog.md) or [Popover](https://ui.jarv.is/components/popover.md), that
container's.

The header takes its top corners from its parent, since browsers don't clip a blurred surface to
its container's rounded corners. In a rounded container, give any elements between the two
`rounded-[inherit]`, as the example's scroll area has. In a [Scroll Area](https://ui.jarv.is/components/scroll-area.md),
turn off `scrollFade`, or the fade at its top edge covers the header.

It renders a `<header>`, which is the page's banner landmark when it isn't inside an `<article>`,
`<aside>`, `<main>`, `<nav>` or `<section>`. Give it `render={<div />}` when it heads a panel
rather than the page.

`ScrollHeaderTitle` repeats the page's heading, which you pass as `watch`. It slides up into the
header once that heading has scrolled under it. Screen readers skip it, since they already reach
the heading itself.

The header sets the container's `scroll-padding-top` to its own height, so a link to an anchor,
or a field that takes focus, lands below it rather than under it. Pass `scrollPadding={false}` to
leave the container alone.

## Composition

- `ScrollHeader`
  - `ScrollHeaderTitle`

## Props

The header waits for the page's first paint before it animates, using the `use-settled` hook,
which installs with it. That way its background and title don't fade in when the page loads
already scrolled.

| Part | Extends |
| --- | --- |
| `ScrollHeader` | `<header>` |
| `ScrollHeaderTitle` | `<span>` |

Base UI's [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides say more about `className`, `style` and `render`.

### ScrollHeader

| Prop                | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------------- | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `offset?`           | `number`                                                 | `0`     | How far below the top of the scroll container the header sticks, in pixels.                                                                                                               |
| `root?`             | `React.RefObject<HTMLElement \| null>`                   | —       | The scroll container. Defaults to the nearest ancestor that scrolls, or the page.                                                                                                         |
| `scrollPadding?`    | `boolean`                                                | `true`  | Sets the scroll container's `scroll-padding-top` to the header's height, so links to anchors and focused fields land below it.                                                            |
| `onScrolledChange?` | `((scrolled: boolean) => void)`                          | —       | Called when content starts or stops scrolling beneath the header.                                                                                                                         |
| `className?`        | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`            | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`           | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### ScrollHeaderTitle

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `watch`      | `React.RefObject<HTMLElement \| null>`                   | —       | The page's own heading. The title slides up into the header once that heading has scrolled under it.                                                                                      |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
