Skip to content

CommentThread

C-41 · Components · Editor (Office)

All elements · CommentThread on the Components page

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

Copies the bun run a11y:approve command for CommentThread.

CommentThread

C-41 OfficeWCAG 2.2 AA · Passed

A comment thread: the anchor quote, the author header (avatar, name, time, actions), the body, nested replies, the composer and the actions. In the pane, in the page margin next to its anchor, or as a popup over the page (PDF sticky notes).

Axis / element Values
data-state active · resolved · draft
data-placement pane · margin · popup
__anchor-quote · __header · __who · __author · __time · __meta header parts
__body · __mention · __reply · __composer · __actions content
States
consistent with a failed seal
Mark RiveraYesterday, 16:20

How do we know the seal failed suddenly? Underwriting will ask.

Jane DoeToday, 09:12

Added the moisture readings in §2.

section 2 of the policy
Jane DoeMonday

Reviewed against the policy schedule.

Jane DoeDraft

Ask Northwind to split ceiling and walls before we approve.

Guidance

When to use

  • Use it for a discussion anchored to a range of document text, a cell or a PDF location.
  • Use data-placement="pane" in the Comments task pane, margin beside the anchor on the page, and popup for PDF sticky notes.
  • Use data-state="active" for the thread tied to the current selection, resolved for closed threads and draft for an unposted comment.
  • Show the anchor quote, the author header, the body, replies and a reply composer.

When to consider something else

  • For activity on a record rather than on document content, use Notifications or a List of events. See NotificationCenter.
  • For a short system message about the document, use a Banner instead of a comment. See Banner.
  • To show many threads together, place them in a Task pane. See TaskPane.

Usability

Do
  • Quote the anchored text in __anchor-quote so the thread makes sense away from the page.
  • Show the author's name and a readable time; the avatar is decoration.
  • Name the composer field after the person being answered, such as "Reply to Jane Doe".
  • Mark @ mentions with __mention.
  • Use Fluent Regular glyphs for Resolve and Post inside .qf-office (README, Icons).
Don’t
  • Don't rely on the dashed border alone to say a comment is a draft, or the gray fill alone for resolved; say it in text such as the time field.
  • Don't hide resolved threads without a filter the user controls.
  • Don't post a reply on Enter alone in a multi-line composer.

Accessibility

Keyboard

CommentThread keyboard
Keys Action
Tab / Shift+Tab Moves through the thread's buttons and the reply field in DOM order.
Enter or Space on Resolve thread Resolves the thread; the binding must announce the change.
Enter or Space on Post reply Posts the reply text; the binding must keep focus in the thread.
Escape in a popup thread The binding must close the popup and return focus to its anchor.

Roles and names

  • Each thread is an <article class="qf-comment"> with aria-labelledby pointing at the author name.
  • The anchor quote is a <blockquote>; the header is a <header> holding __author and __time.
  • The avatar is aria-hidden; the author's name is real text.
  • Icon-only actions (Resolve thread, Post reply) need an aria-label; the composer input needs an aria-label when it has no visible label.
  • The resolved and draft states must be exposed in text, not only through data-state styling.

Focus

  • Selecting a comment anchor in the document should move focus or the active state to its thread, and back.
  • After posting, focus stays in the thread so the user can read the new reply.
  • The composer shows a visible :focus-visible ring.

Other requirements

  • Resolved text uses the muted ink; it must still meet 4.5:1 against the sunken fill (1.4.3).
  • New replies from other people should be announced through a polite live region, not by moving focus (4.1.3).
  • Margin threads are narrower (80% of pane width); they must reflow without clipping text (1.4.10).

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.

CommentThread 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. (4 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. (5 items)

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

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

Latest updates

No recorded changes yet.

All release notes