# Form Actions

The row of buttons at the end of a form, aligned right, left or spread to both edges.

- Category: Forms
- Page: https://wunderui.com/components/form-actions
- Tier: Free

## Install

```bash
npx wunderui-cli add form-actions
```

## Import

```tsx
import { FormActions } from "@/components/blocks/form"
```

## Minimal usage

Then use it:

```tsx
import { Button } from "@/components/ui/button"
import { FormActions } from "@/components/ui/form-actions"

export function Actions() {
  return (
    <FormActions>
      <Button type="button" variant="plain">
        Cancel
      </Button>
      <Button type="submit" variant="gradient">
        Save changes
      </Button>
    </FormActions>
  )
}
```

Expected result: You see two buttons at the right end of the row, 8 px apart: a white Cancel and an indigo Save changes. Put the row at the end of a form and Save sends it.

## Usage

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Field, FieldLabel } from "@/components/ui/field"
import { Form } from "@/components/ui/form"
import { FormActions } from "@/components/ui/form-actions"
import { Input } from "@/components/ui/input"

export function Example() {
  const [name, setName] = useState("WunderUI")
  const [phase, setPhase] = useState<"idle" | "pending" | "success">("idle")

  return (
    <Form
      className="gap-4"
      onFormSubmit={() => {
        setPhase("pending")
        window.setTimeout(() => setPhase("success"), 1200)
      }}
    >
      <Field name="workspace">
        <FieldLabel>Workspace name</FieldLabel>
        <Input
          value={name}
          onChange={(event) => {
            setName(event.target.value)
            setPhase("idle")
          }}
        />
      </Field>
      <FormActions>
        <Button
          type="button"
          variant="plain"
          disabled={phase === "pending"}
          onClick={() => {
            setName("WunderUI")
            setPhase("idle")
          }}
        >
          Cancel
        </Button>
        <Button type="submit" variant="gradient" phase={phase} disabled={name.trim() === ""}>
          {phase === "pending" ? "Saving…" : phase === "success" ? "Saved" : "Save changes"}
        </Button>
      </FormActions>
    </Form>
  )
}
```

## When to use

### Use Form Actions for

- The buttons at the end of a form: Cancel and Save
- The footer of a card, a dialog or a sheet that holds a form
- A bar that sticks to the bottom of a long form, or Back and Continue in a flow of steps

### Use something else

- [Button Group](https://wunderui.com/components/button-group) for buttons that belong to one control, such as a split or a segmented set
- [Dialog](https://wunderui.com/components/dialog) for the footer of a dialog, which lays out its own buttons with DialogFooter
- [Toolbar](https://wunderui.com/components/toolbar) for commands that act on the page or a selection, not on one form

## Keyboard

Form Actions adds no keys. Its buttons are ordinary buttons, in the order you write them.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves through the buttons from left to right as they are written. A disabled button is skipped; a pending button stays in the order and is announced as busy. |
| `Space` or `Enter` | Presses the focused button. A button with `type="submit"` sends the form. |
| `Enter` | In a text field of the same form, presses the first enabled submit button, so the main action does not need a click. |

## Behavior

What the row does itself, and what it leaves to the page.

- **A plain row:** A plain flex row with an 8 px gap and centred items. It has no role and no state; the buttons carry both.
- **Alignment:** End pushes the buttons to the end, start keeps them at the start, between splits first and last to opposite edges. With between, wrap the two end buttons in one div.
- **Wrapping:** On a narrow screen the buttons wrap onto a second line instead of overflowing. For a deliberate column, stack them and put the main action first in the DOM.
- **Order:** The row never reorders anything. Tab follows what you write, so write the buttons in the order they should appear.
- **Pending:** A pending Button keeps its width and colour, shows a spinner and ignores presses, but stays focusable so the person doesn't lose their place. Disable the way out meanwhile.
- **Disabled:** Disable Save only when there is nothing to send, and add a status line that says why. A dimmed button can't explain itself.
- **Sticky and footers:** Make the row sticky with a border and background to keep it in view in a scrolling form, or give it a top border and subtle fill as a card footer. Round the container, not the row.
- **Motion:** The row doesn't move. Buttons change colour quickly and the spinner turns.
- **Reduced motion:** With reduced motion the spinner stops turning. The pending label still says the send is running.

## Anatomy

- `FormActions`: The row. It lays its children out 8 px apart and wraps them onto a second line on a narrow screen; align sets where it sits: end (default), start or between.
- `Secondary action`: The way out of the form: Cancel, Discard or Back. A plain Button that doesn't compete with the main action, and it is disabled while the main action is pending.
- `Main action`: The gradient Button that submits the form, one per row. It shows pending, success or error, with a label that says what is happening.
- `Destructive action`: An action that loses something, such as Delete draft. It sits at the other edge so a quick tap on the main action can't land on it; an irreversible step still needs its own confirmation.

## Best practices

### When to use

- Use Form Actions for the buttons that end a form, dialog, sheet or step. Buttons that act on the page, not the form, belong in a Toolbar.

### Do

- Put the main action last, next to the way out: Cancel, then Save changes. Write both as verbs that say what happens: Create project, not OK.
- Keep the DOM order equal to the screen order, so Tab follows what the eye sees. The main action comes last at the end, first when aligned to the start.
- While saving, show a pending main action with its own label (Saving…) and disable the way out. Afterwards show Saved for a moment.
- Put a destructive action at the opposite edge and group the other two together. Ask in an Alert Dialog before an irreversible delete.
- Match the size of the fields above the row (32, 36 or 40 px) and use one size for every button in it.

### Don't

- Don't put two gradient buttons in a row. One main action per row; the second is a plain Button.
- Don't hide the main action under a menu, and don't disable it without saying why. If there is nothing to save, say so in a status line.
- Don't reorder the buttons with CSS to move the main action. Tab order stays the same and stops matching the screen.

## API reference

### FormActions

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  | The buttons of the row, in the order they should be tabbed. With `align="between"`, give it two children and wrap several buttons of the end in one `div`. |
| align | "start" \| "end" \| "between" | "end" | Where the buttons sit in the row. `end` (the default) puts them at the end, `start` at the start and `between` puts the first child at the start and the last at the end, with the space between. |
| className | string |  | Extra classes for the row. Use them to stack the buttons (`flex-col items-stretch`), to stick the row to the bottom of a scrolling form or to turn it into a card footer. |

## Examples

### Arrangement: a pair, one action, three actions and a stack

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Field, FieldLabel } from "@/components/ui/field"
import { Form } from "@/components/ui/form"
import { FormActions } from "@/components/ui/form-actions"
import { Input } from "@/components/ui/input"

export function Example() {
  const [name, setName] = useState("WunderUI")
  const [phase, setPhase] = useState<"idle" | "pending" | "success">("idle")

  return (
    <Form
      className="gap-4"
      onFormSubmit={() => {
        setPhase("pending")
        window.setTimeout(() => setPhase("success"), 1200)
      }}
    >
      <Field name="workspace">
        <FieldLabel>Workspace name</FieldLabel>
        <Input
          value={name}
          onChange={(event) => {
            setName(event.target.value)
            setPhase("idle")
          }}
        />
      </Field>
      <FormActions>
        <Button
          type="button"
          variant="plain"
          disabled={phase === "pending"}
          onClick={() => {
            setName("WunderUI")
            setPhase("idle")
          }}
        >
          Cancel
        </Button>
        <Button type="submit" variant="gradient" phase={phase} disabled={name.trim() === ""}>
          {phase === "pending" ? "Saving…" : phase === "success" ? "Saved" : "Save changes"}
        </Button>
      </FormActions>
    </Form>
  )
}
```

### Sizes: 32, 36 and 40 px

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Field, FieldLabel } from "@/components/ui/field"
import { Form } from "@/components/ui/form"
import { FormActions } from "@/components/ui/form-actions"
import { Input } from "@/components/ui/input"

export function Example() {
  const [name, setName] = useState("WunderUI")
  const [phase, setPhase] = useState<"idle" | "pending" | "success">("idle")

  return (
    <Form
      className="gap-4"
      onFormSubmit={() => {
        setPhase("pending")
        window.setTimeout(() => setPhase("success"), 1200)
      }}
    >
      <Field name="workspace">
        <FieldLabel>Workspace name</FieldLabel>
        <Input
          value={name}
          onChange={(event) => {
            setName(event.target.value)
            setPhase("idle")
          }}
        />
      </Field>
      <FormActions>
        <Button
          type="button"
          variant="plain"
          disabled={phase === "pending"}
          onClick={() => {
            setName("WunderUI")
            setPhase("idle")
          }}
        >
          Cancel
        </Button>
        <Button type="submit" variant="gradient" phase={phase} disabled={name.trim() === ""}>
          {phase === "pending" ? "Saving…" : phase === "success" ? "Saved" : "Save changes"}
        </Button>
      </FormActions>
    </Form>
  )
}
```

### Placement: end of the form, a sticky bar and a card footer

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Field, FieldLabel } from "@/components/ui/field"
import { Form } from "@/components/ui/form"
import { FormActions } from "@/components/ui/form-actions"
import { Input } from "@/components/ui/input"

export function Example() {
  const [name, setName] = useState("WunderUI")
  const [phase, setPhase] = useState<"idle" | "pending" | "success">("idle")

  return (
    <Form
      className="gap-4"
      onFormSubmit={() => {
        setPhase("pending")
        window.setTimeout(() => setPhase("success"), 1200)
      }}
    >
      <Field name="workspace">
        <FieldLabel>Workspace name</FieldLabel>
        <Input
          value={name}
          onChange={(event) => {
            setName(event.target.value)
            setPhase("idle")
          }}
        />
      </Field>
      <FormActions>
        <Button
          type="button"
          variant="plain"
          disabled={phase === "pending"}
          onClick={() => {
            setName("WunderUI")
            setPhase("idle")
          }}
        >
          Cancel
        </Button>
        <Button type="submit" variant="gradient" phase={phase} disabled={name.trim() === ""}>
          {phase === "pending" ? "Saving…" : phase === "success" ? "Saved" : "Save changes"}
        </Button>
      </FormActions>
    </Form>
  )
}
```

## In context

### Create project: pending, then done

Type a name and press Create. The button shows a spinner and Cancel is disabled while it runs, then it says Created, and Save stays disabled while the name is empty.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Form } from "@/components/ui/form"
import { FormActions } from "@/components/ui/form-actions"
import { Input } from "@/components/ui/input"

export function Example() {
  const [name, setName] = useState("")
  const [phase, setPhase] = useState<"idle" | "pending" | "success">("idle")

  return (
    <Form
      className="gap-4"
      onFormSubmit={() => {
        setPhase("pending")
        window.setTimeout(() => setPhase("success"), 1200)
      }}
    >
      <Field name="project">
        <FieldLabel>Project name</FieldLabel>
        <Input
          value={name}
          placeholder="Spring launch"
          onChange={(event) => {
            setName(event.target.value)
            setPhase("idle")
          }}
        />
        <FieldDescription>Create the project first; you can invite people afterwards.</FieldDescription>
      </Field>
      <FormActions>
        <Button
          type="button"
          variant="plain"
          disabled={phase === "pending"}
          onClick={() => {
            setName("")
            setPhase("idle")
          }}
        >
          Cancel
        </Button>
        <Button type="submit" variant="gradient" phase={phase} disabled={name.trim() === ""}>
          {phase === "pending" ? "Creating…" : phase === "success" ? "Created" : "Create project"}
        </Button>
      </FormActions>
    </Form>
  )
}
```

### Draft: a destructive action at the start

Delete draft sits on the opposite edge from Publish, so a quick tap on the main action cannot land on it. Each button reports what it did in the line above.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { FormActions } from "@/components/ui/form-actions"

export function Example() {
  const [status, setStatus] = useState("Draft last saved at 09:41.")

  return (
    <div className="flex flex-col gap-4">
      <p aria-live="polite" className="text-sm text-text-secondary">
        {status}
      </p>
      <FormActions align="between">
        <Button type="button" variant="plain" onClick={() => setStatus("Draft deleted.")}>
          Delete draft
        </Button>
        <div className="flex items-center gap-2">
          <Button type="button" variant="plain" onClick={() => setStatus("Draft saved just now.")}>
            Save draft
          </Button>
          <Button type="button" variant="gradient" onClick={() => setStatus("Published to the WunderUI workspace.")}>
            Publish
          </Button>
        </div>
      </FormActions>
    </div>
  )
}
```

### Steps: Back and Continue

Back at the start and Continue at the end, each disabled at its end of the flow. The step is announced as it changes.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { FormActions } from "@/components/ui/form-actions"

export function Example() {
  const [step, setStep] = useState(2)

  return (
    <div className="flex flex-col gap-4">
      <p aria-live="polite" className="text-sm text-text-secondary">
        Step {step} of 3: {["Workspace", "Members", "Billing"][step - 1]}
      </p>
      <FormActions align="between">
        <Button type="button" variant="plain" disabled={step === 1} onClick={() => setStep(step - 1)}>
          Back
        </Button>
        <Button type="button" variant="gradient" disabled={step === 3} onClick={() => setStep(step + 1)}>
          Continue
        </Button>
      </FormActions>
    </div>
  )
}
```

## For AI agents

`get_component("form-actions")`

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