# Back Link

> A quiet link back to the page above, or a short trail of levels, that sits over a page title.

- Name: `back-link`
- Status: beta
- Categories: navigation
- File: the install writes `back-link.tsx` to your `ui` alias, `@/components/ui` by default.
- Other registry items: `@arbokui/breadcrumb`. The install adds them.
- Gallery: https://arbokui.com/components/back-link
- Registry item: https://arbokui.com/r/back-link.json

## Install

1. Add the registry to `components.json`. Do this first, once:

   ```bash
   npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json"
   ```

   The command writes this entry. You can also add it by hand:

   ```json
   {
     "registries": {
       "@arbokui": "https://arbokui.com/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control.

2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:

   ```bash
   npx shadcn@latest add @arbokui/theme
   ```

3. Add the component:

   ```bash
   npx shadcn@latest add @arbokui/back-link
   ```

## Use it for

- Put it right above the page title, so people can go up one level: \<BackLink href="/schedule">Schedule\</BackLink>.
- Name the page it goes back to, not the word Back.
- Pass trail for a short path of levels, like Projects / Mobile app / Settings. The last level is the current page.
- With a router, pass its link as render: \<BackLink render={\<Link href="/schedule" />}>Schedule\</BackLink>.
- With no href and no onClick, it is a button that goes back in the browser history.

## Avoid it for

- A long trail of four or more levels. Use Breadcrumb, which can fold the middle into an ellipsis.
- The main way around the app. It only goes up one level.
- A back button inside a dialog or a step flow. Use a Button there.
- Two trails on one page. Each one is a nav named Breadcrumb, so pass a different aria-label to each.

## Props

- `href`: `string`. Where the link goes. With no href, it renders a button that runs onClick, or goes back in history.
- `children`: `ReactNode`. Default `"Back"`. The name of the page it goes back to, like "Schedule". A chevron sits before it.
- `trail`: `{ label: string; href?: string }[]`. Levels in place of one link, joined by slashes. Levels with an href are links. The last level is the current page.
- `onClick`: `(event: MouseEvent<HTMLAnchorElement | HTMLButtonElement>) => void`. Runs on a click. On the button form, it replaces going back in history.
- `render`: `ReactElement`. Renders this element instead of the \<a>, like a router link, with the same props and classes.
- `aria-label`: `string`. On a trail, renames its nav from "Breadcrumb". On a link, replaces its name.
- `className`: `string`. Extra classes. Later classes win, so className='text-foreground' replaces the muted color.

## Accessibility

- The single form is a real \<a> with an href, or a \<button> when there is none, so it works with Tab, Enter, and screen readers.
- Its name is its text, like "Schedule". The chevron is hidden from screen readers.
- A trail is a \<nav> named "Breadcrumb" with an ordered list, built on Breadcrumb. The last level carries aria-current="page".
- The slashes are hidden from screen readers and left out of the list's count.
- Text is muted-foreground on the page, which the theme tests hold to 4.5:1 in light and dark. Hover turns it to the full text color.

## Examples

### Back to the page above

```tsx
<BackLink href="/schedule">Schedule</BackLink>
```

### A short trail

```tsx
<BackLink
  trail={[
    { label: "Projects", href: "/projects" },
    { label: "Mobile app", href: "/projects/mobile-app" },
    { label: "Settings" },
  ]}
/>
```

### Over a page title

```tsx
<div className="flex flex-col gap-1">
  <BackLink href="/members">Members</BackLink>
  <h1 className="text-xl font-semibold">Ava Patel</h1>
</div>
```

### With a router link

```tsx
import Link from "next/link";

<BackLink render={<Link href="/schedule" />}>Schedule</BackLink>
```