Skip to content

Gallery

C-34 · Components · Editor (Office)

All elements · Gallery on the Components page

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

Copies the bun run a11y:approve command for Gallery.

Guidance

When to use

  • Use it in the ribbon when users choose a visual style by its preview, such as paragraph styles, table styles or shape styles.
  • Use the inline form for one row of choices with scroll and expand buttons.
  • Use the expanded form (data-expanded) in a popover when the full set needs labeled sections and footer commands.
  • Use it only when thumbnails are rendered by the engine from the document, so the preview matches the result.

When to consider something else

  • When choices are plain text with no useful preview, use a Select or a Menu. See Select.
  • When the choice is a color, use the Color picker, which names each swatch. See ColorPicker.
  • When the gallery would show in Compact mode, it becomes a value button with a menu (data-ribbon-only); use a Split button pattern there. See SplitButton.
  • For browsing records or files as tiles outside the editor, use Cards or a List. See Card.

Usability

Do
  • Mark the current style with aria-selected="true" so the user sees what applies to the selection.
  • Give every item a text label, either visible in __item-label or as an aria-label on the item.
  • Put commands such as "New table style…" in __footer, not among the items.
  • Pick data-item-size and data-columns to fit the thumbnails without cropping their meaning.
  • Keep the expand and scroll glyphs from the Fluent Regular set used inside .qf-office (README, Icons).
Don’t
  • Don't use a gallery for a short list of text options.
  • Don't rely on the thumbnail alone to identify an item; screen reader and low-vision users need the name.
  • Don't put the scroll buttons in the tab order; keyboard users move through items with arrow keys.

Accessibility

Keyboard

Gallery keyboard
Keys Action
Tab Moves to the gallery's single stop: the current item, then on to the expand button.
Arrow Left / Arrow Right Moves between items in the inline listbox and along a row in the expanded grid.
Home / End Moves to the first or last item.
Arrow Up / Arrow Down in the expanded grid The binding must move to the item above or below, as a grid requires.
Enter or Space Applies the focused item and marks it selected.
Escape in the expanded popover Closes it and returns focus to the expand button.

Roles and names

  • Inline: __viewport is role="listbox" with aria-orientation="horizontal" and an aria-label; each __item is role="option" with aria-selected.
  • Expanded: each __grid is role="grid" labeled by its __section-label, with role="row" rows and role="gridcell" items.
  • __scroll-up, __scroll-down and __expand are buttons with names such as "Previous row" and "More styles"; a scroll button at its limit is disabled.
  • Applying an item is announced through a polite live region ("Heading 1 applied").

Focus

  • One tab stop per listbox or grid (roving tabindex); focus starts on the selected item.
  • Each item shows a :focus-visible ring distinct from the selected border.
  • Closing the expanded form returns focus to the control that opened it.

Other requirements

  • In forced colors the selected item gets a Highlight border and thumbnails a CanvasText border.
  • Thumbnails show document content; text inside them is not a substitute for the item's accessible name (1.1.1).
  • Keep item targets at least 24 by 24 CSS px (2.5.8).

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.

Gallery 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. (6 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. (4 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- gallery --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.

Gallery package
Source css/classic/components/gallery.css
Specimens also use Box · Button · Card · Chip · Icon · Popover · Table · Text · Toolbar
Sprites sprites/icons.svg · sprites/office-icons.svg
React Not yet available: the React binding has not started.

Latest updates

Gallery latest updates
Date Version Breaking Description
2026-10-10 0.1 No Gallery: a selected or current item's label takes --qf-command-pressed-ink on the pressed fill; the secondary ink fell to 4.3:1 on the presentation accent in dark (1.4.3), both skins

All release notes