# Section Nav

A grouped list of links that turns into a scrolling row on small screens.

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

```tsx
"use client";

import {
  BellIcon,
  BlocksIcon,
  CreditCardIcon,
  SettingsIcon,
  ShieldIcon,
  UserIcon,
  UserPlusIcon,
  UsersIcon,
} from "lucide-react";
import * as React from "react";

import { Button } from "@/components/ui/button";
import {
  PageHeader,
  PageHeaderActions,
  PageHeaderContent,
  PageHeaderDescription,
  PageHeaderTitle,
} from "@/components/ui/page-header";
import { SectionNav, SectionNavGroup, SectionNavItem } from "@/components/ui/section-nav";

const groups = [
  {
    label: "Account",
    items: [
      { id: "profile", label: "Profile", icon: UserIcon },
      { id: "security", label: "Security", icon: ShieldIcon },
      { id: "notifications", label: "Notifications", icon: BellIcon },
    ],
  },
  {
    label: "Organization",
    items: [
      { id: "general", label: "General", icon: SettingsIcon },
      { id: "members", label: "Members", icon: UsersIcon },
      { id: "billing", label: "Billing", icon: CreditCardIcon },
      { id: "integrations", label: "Integrations", icon: BlocksIcon },
    ],
  },
];

const pages: Record<string, { description: string; action?: React.ReactNode }> = {
  profile: { description: "How you appear to your teammates.", action: "Save" },
  security: { description: "Keep your account safe." },
  notifications: { description: "Choose what we email you about.", action: "Save" },
  general: { description: "Your workspace's name, address and language.", action: "Save" },
  members: {
    description: "6 people have access to Acme.",
    action: (
      <>
        <UserPlusIcon />
        Invite
      </>
    ),
  },
  billing: { description: "You're on the Team plan, billed monthly." },
  integrations: { description: "Connect Acme to the tools your team uses." },
};

export default function SectionNavSettingsPage() {
  const [active, setActive] = React.useState("general");
  const title = groups.flatMap((group) => group.items).find((item) => item.id === active)?.label;
  const { description, action } = pages[active];

  return (
    <div className="grid w-full grid-cols-1 gap-6 lg:grid-cols-[11rem_minmax(0,1fr)]">
      <SectionNav aria-label="Settings">
        {groups.map((group) => (
          <SectionNavGroup key={group.label} label={group.label}>
            {group.items.map(({ id, label, icon: Icon }) => (
              <SectionNavItem
                key={id}
                href="#"
                active={active === id}
                icon={<Icon />}
                onClick={(event) => {
                  event.preventDefault();
                  setActive(id);
                }}
              >
                {label}
              </SectionNavItem>
            ))}
          </SectionNavGroup>
        ))}
      </SectionNav>
      <PageHeader size="sm" className="self-start">
        <PageHeaderContent>
          <PageHeaderTitle render={<h3 />}>{title}</PageHeaderTitle>
          <PageHeaderDescription>{description}</PageHeaderDescription>
        </PageHeaderContent>
        {action != null && (
          <PageHeaderActions>
            <Button variant="secondary" size="sm">
              {action}
            </Button>
          </PageHeaderActions>
        )}
      </PageHeader>
    </div>
  );
}
```

## 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/section-nav
```

## Usage

```tsx
import { SectionNav, SectionNavGroup, SectionNavItem } from "@/components/ui/section-nav";

export function SettingsNav() {
  return (
    <SectionNav aria-label="Settings">
      <SectionNavGroup label="Account">
        <SectionNavItem href="/settings/profile" active>
          Profile
        </SectionNavItem>
        <SectionNavItem href="/settings/security">Security</SectionNavItem>
      </SectionNavGroup>
      <SectionNavGroup label="Organization">
        <SectionNavItem href="/settings/members">Members</SectionNavItem>
        <SectionNavItem href="/settings/billing">Billing</SectionNavItem>
      </SectionNavGroup>
    </SectionNav>
  );
}
```

Give `SectionNav` an `aria-label` and set `active` on the current page's item. Below the `lg`
breakpoint the list becomes a scrolling row, so place it above the content on small screens. The
active item scrolls into view, and the edges fade wherever there's more to scroll. To keep one
layout at every width, set `orientation`. In a column, a label too long for the nav ends in an
ellipsis rather than widening the nav.

Screen readers announce the active item as the current page. For links to sections of one page,
pass `aria-current="location"` along with `active`.

To use your router's link, pass it to `render` on `SectionNavItem`, as in
`render={<Link to="/settings/profile" />}`.

## Composition

- `SectionNav`
  - `SectionNavGroup`
    - `SectionNavItem`

## Examples

### Without groups

Put `SectionNavItem`s directly in `SectionNav` for a short list.

```tsx
"use client";

import * as React from "react";

import { SectionNav, SectionNavItem } from "@/components/ui/section-nav";

const pages = ["Overview", "Activity", "Deployments", "Analytics", "Logs", "Settings"];

export default function SectionNavWithoutGroups() {
  const [active, setActive] = React.useState("Overview");

  return (
    <SectionNav aria-label="Project" className="w-full lg:w-44">
      {pages.map((page) => (
        <SectionNavItem
          key={page}
          href="#"
          active={active === page}
          onClick={(event) => {
            event.preventDefault();
            setActive(page);
          }}
        >
          {page}
        </SectionNavItem>
      ))}
    </SectionNav>
  );
}
```

### Orientation

`orientation` is `responsive` by default: a row below `lg` and a column from `lg` up. Set it to
`horizontal` to keep the scrolling row at every width, as in a bar of a page's sections, or to
`vertical` to keep the column, as in a menu drawer on a phone.

```tsx
"use client";

import * as React from "react";

import { SectionNav, SectionNavItem } from "@/components/ui/section-nav";
import { preventNavigation } from "@/examples/data";

const pages = ["Overview", "Activity", "Deployments", "Analytics", "Logs", "Settings"];

export default function SectionNavFixedOrientation() {
  const [active, setActive] = React.useState("Overview");

  const items = pages.map((page) => (
    <SectionNavItem
      key={page}
      href="#"
      active={active === page}
      onClick={(event) => {
        preventNavigation(event);
        setActive(page);
      }}
    >
      {page}
    </SectionNavItem>
  ));

  return (
    <div className="flex w-full max-w-md flex-col gap-6">
      <SectionNav aria-label="Project, as a row" orientation="horizontal">
        {items}
      </SectionNav>
      <SectionNav aria-label="Project, as a column" orientation="vertical" className="w-44">
        {items}
      </SectionNav>
    </div>
  );
}
```

### Scrolling

Give `SectionNav` a height to scroll a long list in the sidebar. It's a
[Scroll Area](https://ui.jarv.is/components/scroll-area.md), so it fades at the edges and shows a scrollbar on hover.

```tsx
"use client";

import * as React from "react";

import { SectionNav, SectionNavGroup, SectionNavItem } from "@/components/ui/section-nav";

const groups = [
  { label: "Account", pages: ["Profile", "Security", "Notifications", "Connected apps"] },
  { label: "Organization", pages: ["General", "Members", "Teams", "Roles", "Billing"] },
  { label: "Developers", pages: ["API keys", "Webhooks", "Audit log"] },
];

export default function SectionNavScrolling() {
  const [active, setActive] = React.useState("Webhooks");

  return (
    <SectionNav aria-label="Settings" className="w-full lg:h-64 lg:w-44">
      {groups.map((group) => (
        <SectionNavGroup key={group.label} label={group.label}>
          {group.pages.map((page) => (
            <SectionNavItem
              key={page}
              href="#"
              active={active === page}
              onClick={(event) => {
                event.preventDefault();
                setActive(page);
              }}
            >
              {page}
            </SectionNavItem>
          ))}
        </SectionNavGroup>
      ))}
    </SectionNav>
  );
}
```

## Props

| Part | Extends |
| --- | --- |
| `SectionNav` | [`ScrollArea`](https://ui.jarv.is/components/scroll-area.md) |
| `SectionNavGroup` | `<div>` |
| `SectionNavItem` | `<a>` |

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`.

### SectionNav

| Prop                     | Type                                                                                        | Default        | Description                                                                                                                                                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `overflowEdgeThreshold?` | `number \| Partial<{ xStart: number; xEnd: number; yStart: number; yEnd: number; }>`        | `0`            | The threshold in pixels that must be passed before the overflow edge attributes are applied. Accepts a single number for all edges or an object to configure them individually.                                            |
| `scrollFade?`            | `boolean`                                                                                   | `true`         | Fades the content out at any edge it can scroll past, and keeps focused content clear of the fade. Set `--scroll-fade-size` on the root to change the fade's size (1.5rem by default), or pass `false` to turn it off.     |
| `stickToBottom?`         | `boolean`                                                                                   | `false`        | Starts at the bottom and follows content added there, as a log or a chat does, while the view is at the bottom. When someone scrolls up, the scroll position stays put until they scroll back down.                        |
| `scrollbarGutter?`       | `boolean`                                                                                   | `false`        | Adds room beside the content for each scrollbar while its axis overflows, so the scrollbar doesn't cover the content. The room matches `--scrollbar-size`, which also sets the scrollbars' thickness (0.75rem by default). |
| `hideScrollbars?`        | `boolean`                                                                                   | `false`        | Leaves out the scrollbars. The content still scrolls by wheel, touch and keyboard, and still fades at its edges.                                                                                                           |
| `viewportProps?`         | `Omit<ScrollAreaViewportProps, "children">`                                                 | `{}`           | Props for the viewport, the element that scrolls. Pass `tabIndex: -1` to keep it out of the tab order when the content handles the keyboard itself, as a grid or a list of tabs does.                                      |
| `orientation?`           | `"horizontal" \| "responsive" \| "vertical"`                                                | `"responsive"` | Lays the list out in a column, in a scrolling row, or in a row below the `lg` breakpoint and a column from it.                                                                                                             |
| `className?`             | `string \| ((state: ScrollAreaRootState) => string \| undefined)`                           | —              | CSS class applied to the element, or a function that returns a class based on the component's state.                                                                                                                       |
| `style?`                 | `React.CSSProperties \| ((state: ScrollAreaRootState) => React.CSSProperties \| undefined)` | —              | Style applied to the element, or a function that returns a style object based on the component's state.                                                                                                                    |
| `render?`                | `ComponentRenderFn<HTMLProps, ScrollAreaRootState> \| 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.                                  |

### SectionNavGroup

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label?`     | `React.ReactNode`                                        | —       | The group's label, shown above its items in a column. In a row, the label is hidden and only labels the group for screen readers.                                                         |
| `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. |

### SectionNavItem

| Prop         | Type                                                                      | Default | Description                                                                                                                                                                               |
| ------------ | ------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active?`    | `boolean`                                                                 | `false` | Highlights the item, scrolls it into view and sets `aria-current="page"`. Pass `aria-current` to announce something else, such as `"location"` for a section of the page.                 |
| `icon?`      | `React.ReactNode`                                                         | —       | An icon shown before the label.                                                                                                                                                           |
| `className?` | `string`                                                                  | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                                     | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, SectionNavItemState> \| 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. |
