Skip to content

SaveState

C-42 · Components · Versioning

All elements · SaveState on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for SaveState.

SaveState

C-42WCAG 2.2 AA · Passed

The save indicator beside a document's name: Saving…, Saved, Offline, or Not saved while it retries, with Retry now. A save never makes a version, so the indicator never says one.

Axis / element Values
data-state saving · saved · offline · error
data-placement · data-compact titlebar (glyph takes the bar's ink; automatic inside .qf-overlay__header) / glyph only, words kept for screen readers
__status (role="status") · __icon · __label · __detail the live region and its parts
__retry Retry now, outside the live region; hidden unless data-state="error"
States
Saving…
Saved09:14
Offlinechanges are kept on this device
Not savedretrying in 20 s
In a window title bar (Retry now works)
Assessment report CS-2041.docx
Not savedretrying in 20 s
On a title bar the glyph takes the bar's ink; the words carry the state.

Guidance

When to use

  • Use it beside a document's name, in the editor title bar or on the document screen, to say whether the user's work is safe.
  • Use data-state="saving" while a save is in flight, saved once it is stored, offline while the connection is down and work is kept locally, and error when a save failed and is being retried.
  • In the error state show __retry (Retry now) and say when the next automatic attempt is in __detail.
  • Use data-compact (or rely on the narrow-window rule in a title bar) to show only the glyph when space is short; the words stay in the accessibility tree.

When to consider something else

  • A save never creates a version. To tell the user that a version was published or a checkpoint made, use a Toast. See Toast.
  • For a failure the user must act on before continuing, such as a conflict or a lost checkout, use a Banner in the editor's message bar or a Confirmation. See Banner.
  • For a long upload with a known size, use Progress. See Progress.

Usability

Do
  • Say the state in words: Saving…, Saved, Offline, Not saved.
  • Keep work while offline and say so in __detail ("changes are kept on this device").
  • Retry automatically with backoff and keep Retry now available while the state is error.
  • Use Tabler glyphs in qaction and Fluent Regular glyphs inside .qf-office (README, Icons).
Don’t
  • Don't say "Version saved" or show a version number: saves are not versions.
  • Don't flash Saving… for saves shorter than about half a second; go straight to Saved.
  • Don't rely on the glyph's color; on a title bar the glyph takes the bar's ink.

Accessibility

Keyboard

SaveState keyboard
Keys Action
Tab / Shift+Tab Reaches Retry now when it is shown; the status itself is not a tab stop.
Enter or Space on Retry now Retries the save; the button leaves the tree as the state turns to saving, and focus moves to __status (tabindex -1) instead of being lost.

Roles and names

  • __status is role="status" (polite, atomic): a state change is announced once, without moving focus (4.1.3).
  • Retry now sits outside the live region so its label is not re-read with every change.
  • Glyphs are aria-hidden; __label and __detail carry the meaning.

Focus

  • Retry now shows the standard :focus-visible ring, including on a dark title bar.

Other requirements

  • Change only the text inside __status when the state changes; replacing the element can make screen readers miss the announcement.
  • Throttle announcements: a saving → saved cycle every few seconds should update the text, but bindings may skip announcing Saving… for quick saves.
  • The saving glyph spins; reduced motion stops it (2.3.3).

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

SaveState test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (2 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (3 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- save-state --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

SaveState package
Source css/classic/components/versions.css
Specimens also use Box · Card · Chip · Overlay · Table · Text · Toolbar
Sprites —
React Not yet available: the React binding has not started.

Latest updates

SaveState latest updates
Date Version Breaking Description
2026-10-08 0.1 No SaveState (.qf-save-state): Saving…, Saved, Offline and Not saved with Retry now; a polite status region, the glyph takes a title bar's ink; js/versions.js setSaveState (QF-10840)

All release notes