# Scope List

What an agent asks to access, one scope per row, with a countdown until the request lapses.

- Category: AI & Agents
- Page: https://wunderui.com/components/scope-list
- Tier: Core and Pro

## Install

Scope List ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { ScopeList } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { ScopeList } from "@wunderui/react"

export function Request({ expiresAt }: { expiresAt: Date }) {
  return (
    <ScopeList
      scopes={[
        { title: "Read the docs app", detail: "apps/docs · 412 files" },
        { title: "Open a pull request", detail: "wunder-ui/wunderui · branch tokens-sync" },
      ]}
      expiresAt={expiresAt}
    />
  )
}
```

Expected result: You see a card headed Requested access with a timer at the right, then one row per scope. Under a minute the timer turns amber, and at zero it reads Expired in red.

## When to use

### Use Scope List for

- The access an agent asks for before it runs, one scope per row
- What was granted, with a way to revoke each scope next to it
- A request that lapses, with the time left in the header

### Use something else

- [Tool Permission Row](https://wunderui.com/components/tool-permission-row) for an Allow, Ask or Deny choice for one tool
- [Expiry Timer](https://wunderui.com/components/expiry-timer) for the countdown alone, without a list
- [Approval Card](https://wunderui.com/components/approval-card) for the decision itself, with Approve and Reject and the risk

## Keyboard

The list itself is not interactive and handles no keys. Buttons you put in a row, such as Revoke, are native buttons.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves between the buttons you put in the rows, in reading order. The list and its timer are not tab stops. |
| `Enter` or `Space` | Activates the focused button, for example Revoke. |

When a button removes its own row, move focus yourself, to the next button or to a status line if none is left. The Examples tab shows how.

## Behavior

What the list shows, what its timer does, and what it leaves to you.

- **Read only:** The list only shows scopes: no buttons, no selection, no state. Approve, Reject and Revoke are yours to build around it, and the Examples tab shows each.
- **Rows:** One row per scope, in the order you pass them. A detail can be a plain string for a path or a node with a button.
- **Timer:** With an expiry the header shows Expires in 04:32 and ticks every second. It turns amber when less than a minute is left (adjustable) and reads Expired in red at zero.
- **Announcements:** The timer never reads out the seconds. A screen reader hears Expiring soon once when it turns amber and Expired once when it lapses.
- **After expiry:** The expire callback fires once when time runs out, and nothing changes by itself, so turn the decision off there and say nothing was granted. A new expiry restarts the timer.
- **Date that cannot be read:** An invalid expiry date never ticks. The header reads Expires in with no time and the request never lapses, so pass a valid date or none.
- **No scopes:** An empty list shows just the header, so show a sentence like This run asks for no access instead. The Examples tab shows it.
- **Long text:** Titles and details wrap inside the card, and a long path without spaces breaks too. Nothing is cut off.
- **Semantics:** The section is named by its title, the rows form a list, and icons are hidden from screen readers. Changes are not announced, so say what changed in a status line.
- **Motion:** None. Only the timer text changes, once a second, and reduced motion makes no difference.

## Anatomy

- `ScopeList`: A section named by its title, with a 1 px border, 16 px radius and 16 px padding. The bare option drops all three and leaves only the content.
- `Title`: The heading, Requested access by default, in 14 px semibold text. It is the accessible name of the section.
- `Expiry timer`: An Expiry Timer at the right of the header, shown when an expiry is set. It is grey, turns amber shortly before the end and red once the request has lapsed.
- `Icon tile`: A 28 px tile with an 8 px radius on the indigo tint, holding a 14 px icon (a shield by default). It is decoration and hidden from screen readers.
- `Scope title`: What the agent asks to do, in 13 px medium text. Start with the verb: read, edit, open, delete.
- `Detail`: The target and how much of it, in 12 px monospace text, such as apps/docs · 412 files. It can hold a node, so a button can sit in it.

## Best practices

### When to use

- Use it for what a run asks to access or was granted. For one tool's Allow, Ask or Deny use Tool Permission Row, for the countdown Expiry Timer, for the decision Approval Card.

### Do

- Start each title with the verb the agent will use: read, edit, open, delete. Readers scan down the verbs before the targets.
- Put the target and its size in the detail, in a form people recognise: a path, a branch, a file count. Say there when an action cannot be undone.
- Group by verb when there are more than four scopes or a delete sits next to a read. One list per verb, least risky first.
- Set an expiry for a request that lapses, and turn Approve and Reject off when it runs out. The list does not disable anything itself.
- Give each scope an id when rows can be removed or reordered, so a button inside a row keeps its identity.

### Don't

- Don't pre-approve anything or focus Approve when the request opens. The list shows what is asked, and the decision is the person's.
- Don't fold delete into a broad title such as Full access. Name each action the agent will take.
- Don't put controls in the title. A button like Revoke goes in the detail and needs an aria-label that names the scope.

## API reference

### ScopeList

| Prop | Type | Default | Description |
|---|---|---|---|
| scopes* | Scope[] |  | The scopes, one row each. A scope is `{ id?, icon?, title, detail? }`: `id` is the key, `icon` replaces the shield, `title` is the permission in plain words and `detail` is the target, any node. |
| bare | boolean | false | Drops the border, the radius and the padding of the card, for a list inside a surface of your own. Default `false`. |
| className | string |  | Extra classes for the section, for example `max-w-lg`. |
| detailClassName | string |  | Classes for every detail line, e.g. `font-sans` for prose instead of the monospace default. |
| expiresAt | Date \| string \| number |  | When the request lapses: a `Date`, an ISO string or milliseconds since the epoch. Without it there is no timer. |
| onExpire | () => void |  | Called once when the time runs out. A new `expiresAt` lets it fire again. |
| title | React.ReactNode | "Requested access" | The heading and the accessible name of the list. Default `Requested access`. |
| warnAt | number |  | Milliseconds left at which the timer turns amber. Default `60000`. |

## Examples

### Wording: read, write, delete

### Grouping: one list or one list per verb

### Frame: card or bare

### Warn at: when the timer turns amber

### Detail text and expiry

## In context

### Request: approve or reject before it lapses

A request that lapses after 30 seconds, with nothing approved by default. After a decision or when time is up the buttons go off, and the status line says who decided or that nothing was granted.

### Granted access: revoke one scope

The list is read-only, so Revoke is a button inside each row. Enter or Space revokes it, the row goes, and focus moves to the next Revoke button or, when none is left, to the status line.

### States of a request: loading, failed, empty, loaded

The list shows the scopes it is given; loading, failure and an empty request are yours to show. Keep the list's height while loading, offer another try on failure and use a sentence when empty.

## For AI agents

`get_component("scope-list")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
