FormSection and actions

The building blocks of a page form - sections with a header, the action row, submit and cancel buttons with a pending state, and a confirmation.

A form on a page is built from a few pieces: FormSection groups related fields in a card with a header, FormActions holds the buttons of the form as a whole, SubmitButton and SaveAndContinueButton show a pending state, FormCancelButton asks before it discards changes, and FormSuccess confirms the result. None of them knows a form library: your application binds them.

A settings form with sections and actionsSimulationA server imitated in your browser: shows the interaction, not a working server integration.

Full source examples/ui/form-section.tsx

// apps/docs/examples/ui/form-section.tsx'use client';
import {useState} from 'react';
import {SubmitButton} from '@workspace/active-ui/components/composed/buttons';import {FormActions} from '@workspace/active-ui/components/composed/form-actions';import {FormCancelButton} from '@workspace/active-ui/components/composed/form-cancel-button';import {FormSection} from '@workspace/active-ui/components/composed/form-section';import {FormSuccess} from '@workspace/active-ui/components/composed/form-success';import {Button} from '@workspace/active-ui/components/primitives/button';import {  Field,  FieldLabel,} from '@workspace/active-ui/components/primitives/field';import {Input} from '@workspace/active-ui/components/primitives/input';
const SAVED = {name: 'Northwind pension fund', email: 'office@example.com'};
/** * A settings form in two sections with the form's action row. Change a * field to make the form dirty: Cancel then asks before it discards. Saving * is simulated with a short wait; nothing is sent. */export default function FormSectionExample() {  const [saved, setSaved] = useState(SAVED);  const [values, setValues] = useState(SAVED);  const [isPending, setIsPending] = useState(false);  const [message, setMessage] = useState('');  const isDirty = values.name !== saved.name || values.email !== saved.email;
  const save = (event: React.FormEvent) => {    event.preventDefault();    setIsPending(true);    setMessage('');    window.setTimeout(() => {      setSaved(values);      setIsPending(false);      setMessage('Your changes are saved.');    }, 1200);  };
  return (    <form className="grid w-full max-w-xl gap-6" onSubmit={save}>      <FormSection        title="Organisation"        description="How the organisation appears on statements."      >        <Field>          <FieldLabel htmlFor="org-name">Name</FieldLabel>          <Input            id="org-name"            value={values.name}            onChange={(event) =>              setValues({...values, name: event.target.value})            }          />        </Field>      </FormSection>      <FormSection        title="Contact"        actions={          <Button type="button" variant="outline" size="sm">            Add a contact          </Button>        }        footer={          <p className="text-muted-foreground text-sm">            Last changed: 16 May 2026          </p>        }        variant="compact"      >        <Field>          <FieldLabel htmlFor="org-email">Email</FieldLabel>          <Input            id="org-email"            type="email"            value={values.email}            onChange={(event) =>              setValues({...values, email: event.target.value})            }          />        </Field>      </FormSection>      <FormActions>        <FormCancelButton          label="Cancel"          isDirty={isDirty}          disabled={isPending}          onConfirm={() => {            setValues(saved);            setMessage('');          }}          dialog={{            title: 'Unsaved changes',            description: 'You have unsaved changes. Discard them?',            confirmLabel: 'Discard changes',            cancelLabel: 'Keep editing',          }}        />        <SubmitButton          isPending={isPending}          normalLabel="Save"          disabled={!isDirty}        />      </FormActions>      <FormSuccess message={message} />    </form>  );}

Usage#

TSX

import {SubmitButton} from '@workspace/active-ui/components/composed/buttons';import {FormActions} from '@workspace/active-ui/components/composed/form-actions';import {FormCancelButton} from '@workspace/active-ui/components/composed/form-cancel-button';import {FormSection} from '@workspace/active-ui/components/composed/form-section';
<form onSubmit={save}>  <FormSection title="Organisation" description="How the organisation appears.">    …fields  </FormSection>  <FormActions>    <FormCancelButton      label="Cancel"      isDirty={isDirty}      onConfirm={leave}      dialog={{        title: 'Unsaved changes',        description: 'You have unsaved changes. Discard them?',        confirmLabel: 'Discard changes',        cancelLabel: 'Keep editing',      }}    />    <SubmitButton isPending={isPending} normalLabel="Save" />  </FormActions></form>;

The pieces#

FormSection: a card with an <h3> title, a description and actions on the title's line (an add button belongs there, not below the fields), and a footer row aligned to the end. A description without a title is a muted paragraph. variant="compact" uses less padding. The page title belongs in a page header, one level up.
FormSectionHeader: the same header on its own, for a section with its own frame.
FormActions: the row of the form's actions, aligned to the start with a gap: cancel first, the primary action last. Not for dialog footers, which align to the end, nor for row or toolbar actions. It does not wrap.
SubmitButton: type="submit". While isPending it shows a spinner, keeps its width (minWidthClass) and its name, and is disabled; disabled adds a reason of your own, such as a form without changes.
SaveAndContinueButton: a second action with its own onClick and the same pending state.
CancelButton: a type="button" in the secondary variant, so it never submits.
FormCancelButton: a cancel that leaves the page. A form without changes leaves at once; with changes, a ConfirmActionDialog asks first, with the confirm in the destructive variant. For a cancel that only closes something, use CancelButton.
FormSuccess: a confirmation in a polite live region, centred; nothing renders without a message.

What your application provides#

The form binding, the dirty state, the pending state and what saving and leaving do.
Every visible text, translated: there are no English defaults.
Errors per field, with Field.

Accessibility and keyboard#

The sections are <section> elements with an <h3> title, so the headings outline the form.
A pending submit button keeps its accessible name behind the spinner and cannot be pressed twice.
FormSuccess mounts together with its message. Some screen readers skip a live region that arrives with its text; where the confirmation must be heard, keep an empty role="status" region in the page and fill it, or move focus to the result.

API#

FormSection#

Import from @workspace/active-ui/components/composed/form-section

Props

childrenrequired

Type: ReactNode

The fields / content of the section.

actions

Type: ReactNode

Optional action(s) in the header row, to the right of title and description (requires title). For the add button of a list section: it belongs in the header, on the same line as the title, and not in the footer below the grid.

className

Type: string

Custom CSS class on the section container.

description

Type: string

Optional description below the title.

title

Type: string

Optional section title; appears as an <h3> at the top.

variant

Type: FormSectionVariant
Default: 'default'

Padding variant. Default: "default" (p-6); "compact" (p-4).

Takes only the props listed.

Types

FormSectionVariant

Type: type FormSectionVariant = 'default' | 'compact';

FormSectionProps

The props of FormSection, each described in its prop list on this page.

interface FormSectionProps {
  title?: string;
  description?: string;
  actions?: React.ReactNode;
  children: React.ReactNode;
  footer?: React.ReactNode;
  variant?: FormSectionVariant;
  className?: string;
}

Buttons#

CancelButton

Props

labelrequired

Type: string

The translated label. Required, with no English default.

className

Type: string

Classes for the button.

disabled

Type: boolean
Default: false

Disables the button.

size

Type: ButtonSize
Default: 'sm'

The Button size.

variant

Type: ButtonVariant
Default: 'secondary'

The Button variant.

Events

Called by the component when something happens.

onClickrequired

Type: MouseEventHandler<…>

Click handler. REQUIRED — a CancelButton without a handler is inert and almost always a latent bug. For navigate-away forms with isDirty-checks use the higher-level <FormCancelButton> instead, which wires this internally.

Takes only the props listed.

SaveAndContinueButton

Props

isPendingrequired

Type: boolean

Shows a spinner and disables the button while the action runs.

normalLabelrequired

Type: string

The translated label. Required, with no English default.

className

Type: string

Classes for the button.

disabled

Type: boolean
Default: false

Disables the button for a reason of the caller's own, such as a form without changes. It combines with isPending and never overrides it: a pending button is always disabled, also with disabled={false}, so a second activation cannot start the same action again.

minWidthClass

Type: string
Default: 'min-w-[160px]'

A minimum width, so the button keeps its width when the spinner replaces the label.

size

Type: ButtonSize
Default: 'sm'

The Button size.

variant

Type: ButtonVariant
Default: 'default'

The Button variant.

Events

Called by the component when something happens.

onClickrequired

Type: () => void

Saves and moves on; the button is type="button".

Takes only the props listed.

SubmitButton

Props

isPendingrequired

Type: boolean

Shows a spinner and disables the button while the action runs.

normalLabelrequired

Type: string

The translated label. Required, with no English default: it stays the button's accessible name while pending, behind the spinner.

className

Type: string

Classes for the button.

disabled

Type: boolean
Default: false

minWidthClass

Type: string
Default: 'min-w-[110px]'

A minimum width, so the button keeps its width when the spinner replaces the label.

size

Type: ButtonSize
Default: 'sm'

The Button size.

type

Type: "button""reset""submit"
Default: 'submit'

The button type.

variant

Type: ButtonVariant
Default: 'default'

The Button variant.

Takes only the props listed.

Types

CancelButtonProps

The props of CancelButton, each described in its prop list on this page.

interface CancelButtonProps {
  label: string;
  variant?: ButtonVariant;
  size?: ButtonSize;
  onClick: React.MouseEventHandler<HTMLButtonElement>;
  disabled?: boolean;
  className?: string;
  [x: string]: unknown;
}

SaveAndContinueButtonProps

The props of SaveAndContinueButton, each described in its prop list on this page.

interface SaveAndContinueButtonProps {
  isPending: boolean;
  normalLabel: string;
  onClick: () => void;
  variant?: ButtonVariant;
  size?: ButtonSize;
  className?: string;
  minWidthClass?: string;
  disabled?: boolean;
  [x: string]: unknown;
}

SubmitButtonProps

The props of SubmitButton, each described in its prop list on this page.

interface SubmitButtonProps {
  isPending: boolean;
  normalLabel: string;
  type?: 'submit' | 'button' | 'reset';
  variant?: ButtonVariant;
  size?: ButtonSize;
  className?: string;
  minWidthClass?: string;
  disabled?: boolean;
  [x: string]: unknown;
}

FormCancelButton#

FormCancelButton

Props

dialogrequired

Type: FormCancelButtonDialogLabels

Translated labels for the confirmation dialog. REQUIRED.

isDirtyrequired

Type: boolean

Whether the form has unsaved changes. When true, clicking the button opens the discard-changes confirmation dialog. When false, onConfirm is called immediately (no dialog shown).

labelrequired

Type: string

Visible label of the Cancel button itself. REQUIRED — caller passes a translated string via t("common.button.cancel").

disabled

Type: boolean
Default: false

Disables the Cancel button (e.g. while a save is in progress).

Events

Called by the component when something happens.

onConfirmrequired

Type: () => void

Called when the user confirms they want to discard changes (or when the form was pristine). Typically () => router.push(parentRoute).

Takes only the props listed.

Types

FormCancelButtonDialogLabels

interface FormCancelButtonDialogLabels {
  title: string;
  description: string;
  confirmLabel: string;
  cancelLabel: string;
}

FormCancelButtonProps

The props of FormCancelButton, each described in its prop list on this page.

interface FormCancelButtonProps {
  label: string;
  isDirty: boolean;
  onConfirm: () => void;
  disabled?: boolean;
  dialog: FormCancelButtonDialogLabels;
}

Other parts#

FormSectionHeader

Props

titlerequired

Type: string

The section title, an <h3>.

actions

Type: ReactNode

Optional action(s) on the right of the header row, on the same line as the title: the add button of a list section belongs in the header, not below the grid. Below sm the action drops below the text.

className

Type: string

Classes for the header.

description

Type: string

A muted line below the title.

descriptionClassName

Type: string

Classes for the description.

titleClassName

Type: string

Classes for the title.

Takes only the props listed.

Types

FormSectionHeaderProps

The props of FormSectionHeader, each described in its prop list on this page.

interface FormSectionHeaderProps {
  title: string;
  description?: string;
  actions?: React.ReactNode;
  className?: string;
  titleClassName?: string;
  descriptionClassName?: string;
}

FormActions

Props

childrenrequired

Type: ReactNode

The actions, in reading order. The convention is: cancel on the left, the primary action on the right.

The order is deliberately the caller's responsibility. A cancel/primary prop would introduce roles into this component, and it would then know what "cancel" and "save" mean — exactly the domain knowledge active-ui keeps out.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

Types

FormActionsProps

The props of FormActions, each described in its prop list on this page.

interface FormActionsProps extends React.ComponentProps<'div'> {
  children: React.ReactNode;
}

FormSuccess

Props

className

Type: string

Classes for the status region.

message

Type: string

The translated confirmation. Without it nothing renders.

Takes only the props listed.