# Outline
Links to the sections of a page, marking the one in view.
Source: [outline.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/outline.tsx)
```tsx
import { Outline, OutlineItem } from "@/components/ui/outline";
const sections = [
{
id: "guide-overview",
title: "Overview",
level: 1,
body: [
"This guide takes a new project from an empty folder to a deployed site. Each step builds on the one before it, so work through them in order the first time.",
"Most steps take a few minutes. Deploying takes longer the first time, while the build cache warms up.",
],
},
{
id: "guide-installing",
title: "Installing",
level: 1,
body: [
"Install the command-line tool with your package manager, then sign in. The tool remembers your account, so you only sign in once on each computer.",
"Run the init command in an empty folder. It asks for a project name and writes a config file with sensible defaults.",
],
},
{
id: "guide-configuring",
title: "Configuring",
level: 1,
body: [
"The config file sets where the site builds from and which commands run. Leave the defaults alone until something needs to change.",
],
},
{
id: "guide-environment",
title: "Environment variables",
level: 2,
body: [
"Keep secrets out of the config file. Add them in the dashboard instead, where each one can differ between preview and production.",
"A build reads variables when it starts, so redeploy after changing one.",
],
},
{
id: "guide-deploying",
title: "Deploying",
level: 1,
body: [
"Push to the main branch to deploy to production. Every other branch gets a preview address of its own, which updates on each push.",
"If a deploy fails, its log shows the step that failed and the output just before it.",
],
},
];
export default function OutlineArticle() {
return (
);
}
```
## 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/outline
```
## Usage
```tsx
import { Outline, OutlineItem } from "@/components/ui/outline";
export function OnThisPage() {
return (
InstallationUsageExamples
Sizes
);
}
```
Link each `OutlineItem` to a heading's id. As the page scrolls, the outline marks the last heading
that has reached the top, or the last one once the page can't scroll further, and the line beside
it slides to follow. It follows whichever element the headings scroll in, the window or a panel,
and checks again when its links change.
Clicking a link scrolls its heading smoothly into place and moves focus to it, so Tab carries on
from that section. Scrolling the headings yourself during the animation takes over from it, and so
does the scroll stopping anywhere else. When the headings scroll with the window, the heading's id
goes in the address once it arrives. A heading lands below the scroller's `scroll-padding-top` and
its own `scroll-margin-top`, and it counts as reached at the same point, so make room there for any
header fixed over the content.
A link's `value` is the part of its `href` after `#`, unless you pass one. Only links to the
current page scroll this way: other links, and links whose `onClick` calls `preventDefault`, such
as a router's link passed to `render`, navigate as they would anyway, and the outline only marks
them.
`label` names the outline and shows above the links. Without it, give `Outline` an `aria-label`.
This site's own On this page column is an `Outline`.
## Composition
- `Outline`
- `OutlineItem`
## Examples
### Levels
`level` indents a link under the one before it, from `1` to `4`.
```tsx
import * as React from "react";
import { Outline, OutlineItem } from "@/components/ui/outline";
export default function OutlineLevels() {
const [value, setValue] = React.useState("color");
return (
IntroductionFoundations
Tokens
Color
Spacing
Typography
Components
);
}
```
### Controlled
Pass `value` and `onValueChange` to choose the marked section yourself. The outline still calls
`onValueChange` as the page scrolls and when a link is clicked.
```tsx
import * as React from "react";
import { Button } from "@/components/ui/button";
import { Outline, OutlineItem } from "@/components/ui/outline";
const steps = [
{ value: "summary", title: "Summary" },
{ value: "details", title: "Details" },
{ value: "results", title: "Results" },
{ value: "next-steps", title: "Next steps" },
];
export default function OutlineControlled() {
const [value, setValue] = React.useState("details");
const index = steps.findIndex((step) => step.value === value);
return (