Forms

FormActions

Action bar for the end of a form: a summary on the left, the secondary then primary buttons on the right, an optional failed-save alert above them, and an option to stay at the bottom of a long form.

import { FormActions } from '@lostgradient/cinder';
formactionssticky
01

Overview

Reference usage

FormActions is the bar at the end of a form. The left side says where the form stands: an unsaved-change count ("2 unsaved changes") and the effect of saving ("Saving raises the policy revision."). The right side holds the buttons, secondary first and the primary submit last, so it sits rightmost. A top divider and the page's canvas fill set the bar apart from the fields above it.

  • Sticky: sticky keeps the bar at the bottom of the nearest scrolling container, so Save is in reach however long the form gets. The bar sits in the flow at the end of the form, so the content above it needs no bottom padding of its own, and it clears the home indicator and rides above the on-screen keyboard. While it is mounted it publishes its height so the toast region sits above it.
  • Failed save: error (and errorTitle) draw a danger alert above the buttons. The fields keep what the person entered and Save keeps its label as the retry.
  • Narrow: below 28rem of bar width the summary takes its own line and the buttons share the row under it.

Save stays enabled while the form is invalid. Form moves focus to the first field with a problem when it is pressed.

Usage

svelte 
<script lang="ts">
  import { Button, Form, FormActions } from '@lostgradient/cinder';
</script>

<Form onSubmit={() => undefined}>
  <FormActions sticky unsavedChanges={2}>
    {#snippet summary()}Saving raises the policy revision.{/snippet}
    {#snippet end()}
      <Button variant="secondary">Reset to default</Button>
      <Button type="submit" variant="primary">Save</Button>
    {/snippet}
  </FormActions>
</Form>
Live preview

Summary left, Cancel then primary right

2 tools from GitHub will join Capabilities.

02

When to use

Use when
  • A form's Save and Cancel belong in one bar with a line of status beside them, such as "N unsaved changes" or what saving will do.
  • A long form's Save must stay in reach, with the effect of saving named beside it.
Avoid when
  • The bar belongs to a page that is not a form, such as a run's Send a message and Cancel run — use docked-action-bar.
  • The actions belong to a dialog or drawer — use the overlay's own footer.
03

Examples

Summary left, Cancel then primary right

The bar at the end of a form: a summary of what the primary button will do on the left, and the secondary Cancel then the primary on the right, under a top divider. The primary names how many tools join and follows the number of checked tools.

A failed save

A failed save draws a danger alert above the buttons. The choices stay as ticked, and Save keeps its label as the retry beside Reset to default.

Sticky bar on a long form

sticky keeps the bar at the bottom of the nearest scrolling container, so the only Save is in reach however long the form gets: the summary "Not saved yet", then Cancel, then Save.

Unsaved changes and the effect of saving

Once something changes the bar counts the unsaved changes in neutral text and names what saving does ("Saving raises the policy revision."), with Reset to default then Save on the right. Untick a model to see the count.

04

Props

Props for form-actions
Name
Type
Default
Description
label text 'Form actions' Accessible name of the bar, read as the name of its group.
unsavedChanges number 0 How many changes the form holds that are not saved. Above zero the bar's left side reads "1 unsaved change" or "N unsaved changes" in neutral text; at zero it says nothing.
sticky boolean false Keeps the bar at the bottom of the nearest scrolling container, so Save is in reach however long the form gets. It clears the home indicator and rides above the on-screen keyboard.
error text What a failed save says, in a danger alert above the buttons: "Couldn't save. Interborough didn't answer. Your choices are still here." The first sentence is drawn as the title when errorTitle is not set. The buttons keep their labels, so Save is the retry.
errorTitle text Bold lead-in for error, such as "Couldn't save."
summary Snippet | undefined The left side of the bar: a status line such as "Not saved yet", or the effect of saving ("Saving raises the policy revision."). Follows the unsaved-change count when there is one.
start Snippet | undefined Controls kept at the start of the bar, after the summary and before the buttons, such as a Delete outside the main pair.
end required snippet The buttons at the end of the bar, secondary first and the primary submit last, so it sits rightmost: Cancel, then Save.