# Action

Everything the user presses: commands, links, navigation and choices. With `href` it renders a link, without one a `<button>`.

Renders: `button` `a` · Intents: [41](#intents-it-renders) · Domains: [`action.*`](https://www.prongs.dev/docs/intents/action.md) [`nav.*`](https://www.prongs.dev/docs/intents/nav.md) [`choice.*`](https://www.prongs.dev/docs/intents/choice.md)

## Examples

### Commands

Named for what they do. The look follows from the meaning: deleting is destructive, cancelling is quiet.

```tsx
<Layout intent="layout.actions">
  <Action intent="action.cancel">Cancel</Action>
  <Action intent="action.save">Save changes</Action>
  <Action intent="action.delete">Delete</Action>
</Layout>
```

### Links

With `href` the same component renders a link.

```tsx
<Text intent="text.body">
  Read the <Action intent="action.navigate" href="/docs/what-is-an-intent">guide to intents</Action> before you add one.
</Text>
```

### On and off

`pressed` sets `aria-pressed`, and the intent styles the pressed state.

```tsx
<Layout intent="layout.toolbar">
  <Action intent="choice.filter" pressed>All</Action>
  <Action intent="choice.filter" pressed={false}>Unread</Action>
  <Action intent="choice.filter" pressed={false}>Starred</Action>
</Layout>
```

### The page you are on

`current` sets `aria-current` on navigation.

```tsx
<Layout intent="layout.group" className="flex-row gap-5">
  <Action intent="nav.page" href="#current-page" current>Overview</Action>
  <Action intent="nav.page" href="#current-page">Activity</Action>
  <Action intent="nav.page" href="#current-page">Settings</Action>
</Layout>
```

### An icon alone

Without visible text, `label` is required: it is the accessible name.

```tsx
<Action intent="action.dismiss" icon={<X aria-hidden className="size-4" />} label="Dismiss" />
```

## Intents it renders

3 domains, each with its own page of neighbours and examples. The intent decides the element; these are the starter intents.

### Action [`action.*`](https://www.prongs.dev/docs/intents/action.md)

27 intents

| Intent | Use it for | Resolves to |
|---|---|---|
| [`action.submit`](https://www.prongs.dev/docs/intents/action/submit.md) | Sends a form | `<button>` |
| [`action.save`](https://www.prongs.dev/docs/intents/action/save.md) | Keeps changes the user made to something that already exists | `<button>` |
| [`action.create`](https://www.prongs.dev/docs/intents/action/create.md) | Makes something new: a post, project, page or item | `<button>` |
| [`action.start`](https://www.prongs.dev/docs/intents/action/start.md) | Begins the main flow a page exists for: get started, sign up, try it | `<a>` |
| [`action.guide`](https://www.prongs.dev/docs/intents/action/guide.md) | The quieter call to action beside the main one, opening the guide to it: get started, read the docs | `<button>` |
| [`action.next`](https://www.prongs.dev/docs/intents/action/next.md) | Moves to the next step of a multi-step flow, or out of a finished one | `<button>` |
| [`action.skip`](https://www.prongs.dev/docs/intents/action/skip.md) | Moves to the next or previous item in a sequence someone steps through: the next track, the previous episode, the next photo in a dialog.media | `<button>` |
| [`action.back`](https://www.prongs.dev/docs/intents/action/back.md) | Returns to the previous step of a flow without losing work | `<button>` |
| [`action.signout`](https://www.prongs.dev/docs/intents/action/signout.md) | Ends the current session and signs the person out | `<button>` |
| [`action.retry`](https://www.prongs.dev/docs/intents/action/retry.md) | Repeats something that failed or needs doing again: try again, resend an email | `<button>` |
| [`action.confirm`](https://www.prongs.dev/docs/intents/action/confirm.md) | Agrees to a decision the interface just asked about, usually in a dialog | `<button>` |
| [`action.cancel`](https://www.prongs.dev/docs/intents/action/cancel.md) | Abandons the current task without keeping changes | `<button>` |
| [`action.edit`](https://www.prongs.dev/docs/intents/action/edit.md) | Opens something that exists so it can be changed | `<button>` |
| [`action.add`](https://www.prongs.dev/docs/intents/action/add.md) | Puts an existing thing into a list or collection: add a source, add a member | `<button>` |
| [`action.remove`](https://www.prongs.dev/docs/intents/action/remove.md) | Takes an item out of a list without destroying it: remove a source, unsubscribe | `<button>` |
| [`action.delete`](https://www.prongs.dev/docs/intents/action/delete.md) | Permanently destroys data | `<button>` |
| [`action.share`](https://www.prongs.dev/docs/intents/action/share.md) | Sends something to other people or copies a link to it | `<button>` |
| [`action.copy`](https://www.prongs.dev/docs/intents/action/copy.md) | Copies the short text beside it, like a command, as an icon alone sized to the line. It stays pressable inside a card its link covers | `<button>` |
| [`action.open`](https://www.prongs.dev/docs/intents/action/open.md) | Opens a piece of content to read or view it: an article title, "open original", a preview | `<a>` |
| [`action.inspect`](https://www.prongs.dev/docs/intents/action/inspect.md) | Opens the details of a record in a table, on its name: the whole row becomes clickable and lights up on hover, while the other controls in it, like its menu, stay clickable | `<button>` |
| [`action.toggle`](https://www.prongs.dev/docs/intents/action/toggle.md) | Turns a state on or off and shows which: follow, subscribe, like. Pass pressed={on} | `<button>` |
| [`action.utility`](https://www.prongs.dev/docs/intents/action/utility.md) | A small helper command that changes no important data: refresh, mark all read | `<button>` |
| [`action.dismiss`](https://www.prongs.dev/docs/intents/action/dismiss.md) | Closes or hides something without changing data: a dialog, notice or menu | `<button>` |
| [`action.reveal`](https://www.prongs.dev/docs/intents/action/reveal.md) | Shows or hides content in place: show password, show more | `<button>` |
| [`action.navigate`](https://www.prongs.dev/docs/intents/action/navigate.md) | Goes to another page or place from inside a sentence: an inline link | `<a>` |
| [`action.more`](https://www.prongs.dev/docs/intents/action/more.md) | A link on its own line to more about what is above it, with an arrow after it: Learn more, See all, Full changelog. Write only the words; the arrow (Lucide arrow-right) is added | `<button>` |
| [`action.sort`](https://www.prongs.dev/docs/intents/action/sort.md) | Sorts a table by a column: the button inside its th. Put aria-sort="ascending" or "descending" on the th of the sorted column; the arrow follows it | `<button>` |

### Navigation [`nav.*`](https://www.prongs.dev/docs/intents/nav.md)

10 intents

| Intent | Use it for | Resolves to |
|---|---|---|
| [`nav.home`](https://www.prongs.dev/docs/intents/nav/home.md) | The site or product name, linking to the home page | `<a>` |
| [`nav.page`](https://www.prongs.dev/docs/intents/nav/page.md) | A link to a top-level page in site navigation. Pass current on the page you are on | `<a>` |
| [`nav.area`](https://www.prongs.dev/docs/intents/nav/area.md) | A link to one area of the site that has its own sidebar: Docs, Reference. Pass current on the open one; it is marked by full-strength text, with no underline | `<a>` |
| [`nav.entry`](https://www.prongs.dev/docs/intents/nav/entry.md) | The name of an entry in an index or table, linking to its page: an intent in the vocabulary list | `<a>` |
| [`nav.item`](https://www.prongs.dev/docs/intents/nav/item.md) | The title of an item in a collection, opening its page. The link covers the item, so the whole item can be pressed; give the item position: relative | `<a>` |
| [`nav.view`](https://www.prongs.dev/docs/intents/nav/view.md) | Switches which view of the same content is shown: Following / For you, list / grid. Pass pressed on the active view | `<a>` |
| [`nav.dot`](https://www.prongs.dev/docs/intents/nav/dot.md) | One dot in a row over a photo that shows which of a set is open, and opens that one: the photos in a dialog.media. Pass current on the one shown, and a label like "Photo 2 of 5" | `<a>` |
| [`nav.step`](https://www.prongs.dev/docs/intents/nav/step.md) | One step in a multi-step flow. Pass current on the active step | `<a>` |
| [`nav.paging`](https://www.prongs.dev/docs/intents/nav/paging.md) | One link in a layout.pager below a long list or table: a page number, Previous or Next. Pass current on the page shown | `<a>` |
| [`nav.sequel`](https://www.prongs.dev/docs/intents/nav/sequel.md) | The previous or next page at the foot of a guide read in order, with an arrow pointing its way. Put the icon on the side it points to | `<a>` |

### Choice [`choice.*`](https://www.prongs.dev/docs/intents/choice.md)

4 intents

| Intent | Use it for | Resolves to |
|---|---|---|
| [`choice.option`](https://www.prongs.dev/docs/intents/choice/option.md) | One of a small set of options for a setting: theme, layout, a category. Pass pressed on the chosen one | `<button>` |
| [`choice.filter`](https://www.prongs.dev/docs/intents/choice/filter.md) | Narrows which items are shown: All, Unread, a source. Pass pressed while it applies | `<button>` |
| [`choice.color`](https://www.prongs.dev/docs/intents/choice/color.md) | Picks a colour from presets. Pass the colour as vars={{ "--choice-color": value }} and pressed on the chosen one | `<button>` |
| [`choice.open`](https://www.prongs.dev/docs/intents/choice/open.md) | Shows what is picked and opens the choices to change it: a sort order, sources. The trigger of a Popover picker | `<button>` |

## Props

Plus its element’s usual attributes (`id`, `onClick`, `aria-*`, `data-*`) and the shared layout props below. No `className` or `style`.

| Prop | Type | What it does |
|---|---|---|
| `intent` (required) | `ActionIntent` | What pressing it does: [`action.*`](https://www.prongs.dev/docs/intents/action.md), [`nav.*`](https://www.prongs.dev/docs/intents/nav.md) or [`choice.*`](https://www.prongs.dev/docs/intents/choice.md). |
| `href` | `string` | Makes it a link (through the `LinkComponent` in `config.ts`, e.g. `next/link`). |
| `pressed` | `boolean` | On or off, for toggles, choices and views. Sets `aria-pressed`; the intent styles it. |
| `current` | `boolean` | Marks the page or step you are on. Sets `aria-current`; the intent styles it. |
| `icon` | `ReactNode` | An icon shown before the text, or alone. |
| `label` | `string` | The accessible name. Required when there is no visible text (an icon alone). |
| `disabled` | `boolean` | Turns it off. A disabled link loses its `href`. |
| `type` | `'button' \| 'submit' \| 'reset'` | Buttons are `type="button"` unless the intent says otherwise ([`action.submit`](https://www.prongs.dev/docs/intents/action/submit.md) is `submit`). |
| `vars` | `Record<`--${string}`, string \| number>` | Values that come from data, as CSS variables the intent reads: `vars={{ '--accent': user.color }}`. |
| `unsafeClassName` | `string` | Bypasses the intent. Needs a `// prongs-unsafe: <reason>` comment on the line above, and `prongs check` counts it. |

### Layout props

Where the element sits, never how it looks. Spacing between elements comes from the parent [`<Layout>`](https://www.prongs.dev/docs/components/layout.md).

| Prop | Type | What it does |
|---|---|---|
| `align` | `'start' \| 'center' \| 'end'` | On text, the text alignment. On anything else, pushes it to that end of its row or column. |
| `width` | `'auto' \| 'full' \| 'prose' \| 'sm' \| 'md' \| 'lg'` | Full width, or a maximum width. |
| `hideBelow` | `'sm' \| 'md' \| 'lg'` | Hidden on screens narrower than this breakpoint. |
| `showBelow` | `'sm' \| 'md' \| 'lg'` | Shown only on screens narrower than this breakpoint. |
| `truncate` | `boolean` | One line, cut off with an ellipsis. |
| `nowrap` | `boolean` | Keeps the text on one line. |

## Rules

- Name it for what it does ([`action.delete`](https://www.prongs.dev/docs/intents/action/delete.md)), not how it looks. `prongs check` warns when its label or handler says something else.
- State goes in `pressed` or `current`, never in a different intent or extra classes.
- An icon alone needs `label`.
- No `className` or `style`.