Skip to content

Candor 5.1.0

Choose a tag to compare

@arunk3 arunk3 released this 13 Nov 17:06
· 8 commits to main since this release

Released 2026-11-13.

A minor, with CLI 3.1.0 and @candor-ui/react 5.1.0; nothing breaks a 5.0 project. The fixes 5.0 held back so its
breaks could be read on their own: focus that stays put, links your router follows, locked controls that say why, and
text that isn't joined in code. Six Pro items are new (link, merge-refs, use-settle, live-rows,
email-heading and user-message-actions), so the kit has 407 items: 74 free and 376 in Pro.

What to do: npx candor-ui@3 update --to 5.1.0 takes a 5.0 project to 5.1.0, with no codemod. If you use
@candor-ui/react, install 5.1.0, which carries the free fixes to Locked, Tooltip, ToolCall, Composer and
Progress. The changes a 5.0 app sees, each with what to do:

  • Inbox and ApprovalQueue (Pro) keep their own selection when you pass onSelectedChange without selected: a
    ticked item shows ticked, and the callback is still called. In 5.0 the tick never showed. Pass selected to hold the
    selection yourself: once you have passed it, the list keeps none of its own, so clearing it to undefined draws none,
    as in 5.0.
  • ConfirmButton (Pro) stays armed for 6 seconds by default in English (4 in 5.0): left out, armedFor is long
    enough to hear the armed announcement at a slow screen-reader rate and then press again, in whole seconds and never
    under 4, and the announcement says how long. Pass armedFor={4000} to keep 5.0's window; a test that waited 4
    seconds for it to disarm waits for the new window or sets armedFor.
  • Six data types' locked field accepts null (string | null | undefined): PaletteItem, ScopeLevel,
    SettingsItem, DashboardTileView, PermissionModeOption and PlanAutonomyOption. Code that builds them is
    unchanged; code that reads one into a string | undefined variable fails the type check: add ?? undefined.
  • Inside a HeadingScope, some headings sit one level below it, as 5.0's rule says, where 5.0 ignored the scope:
    the loading, empty and error heading of Inbox, SessionList, NotificationCenter, AgentRoster, ApprovalQueue,
    TraceViewer, EvalScorecard, MembersTable, AuditLog and ResultTable; A2uiSurface's model headings; EmailPreview's
    title; and AccessRequest's title, a <p> in 5.0, which is a heading inside a scope or with its new headingLevel.
    Outside a scope each draws what it drew in 5.0 (<h2>; A2uiSurface's levels; EmailPreview's <h3>; AccessRequest's
    <p>). A test that found one of them by level inside a scope looks one below the scope, or passes headingLevel; a
    test that found AccessRequest's title as text inside a scope finds it by role heading.
  • A stacked Carousel (Pro) changes slide on a finger or pen swipe only: a mouse drag over a slide selects its text.
    The slide change a person makes is announced ("2 of 3", carousel.slideOf).

Translators: these keys are new. Until you translate them, each says its English words.

  • graphView.putBack; modelKey.saving; dockWindow.goToWindow and goToWindowTitle.
  • board.unplaced (one and other) and board.columns; dataTable.sortCleared.
  • usageMeters.amount, usedOfLimit, limitAfter, unitAfter and withPending. The keys UsageMeters read in 5.0
    are still read.
  • runTree.readoutStatus and readoutJoin. from, after and verdictNote are still read, as their placeholders.
  • The Premium templates' strings that held " · " (agentOpsConsole.topLine and topLineStopped,
    approvalsInbox.owner, member, ruleHeading, waitingLine and requestDescription,
    supportCopilot.threadCustomerLine and draftCardHeader) take {separator}, the locale's separator, in its place;
    agentOpsConsole.startedBy and approvalsInbox.appliedBy no longer hold it, since the template joins them. An
    override that kept its own " · " in startedBy or appliedBy shows it twice: take it out.

Some DOM your own CSS or tests may match has changed:

  • FilterChips (Pro): a chip's label and its value are each in their own <bdi>.
  • Board (Pro): the scrolling region keeps the board's label and the group of columns inside it is named
    "Columns of {label}"; the region's description says how many cards are in no column.
  • EmailPreview (Pro): the title carries data-slot="email-heading", drawn by the new email-heading part.
  • SheetContent (Pro) carries data-edge (top, right, bottom or left, flipped for RTL).
  • CardDeck (Pro): the hint is clipped while hidden, not invisible, so a screen reader's browse mode finds it.
  • Inbox and ApprovalQueue (Pro): the rows' list carries data-slot="live-rows", drawn by the new live-rows part.
  • A stacked Carousel (Pro): the slides' row is aria-live="off" ("polite" in 5.0), and CarouselStatus has no
    aria-live, since the carousel says a slide change the person makes once itself, through Candor's announcer. A test
    that asserted either live region checks the status's text, or the announcement, instead. A sliding carousel's are
    unchanged.
  • ToolCall and SearchTrace: a row that finishes with nothing to show while focus is on it keeps its locked button
    until focus leaves; then it is text, as in 5.0.

Corrected in the 5.0 upgrade notes

scripts/breaking.json's 5.0.0 entries, the Upgrading to 5.0 page
and what update prints going to 5.1.0 or later say these now. update --to 5.0.0 reads the 5.0.0 snapshot, frozen as
released, so it prints the old text; the page says so. The 5.0.0 section below is left as it was released.

  • heading-default (CLI-36): the free PermissionPrompt draws <h2> by default since 5.0 and reads no
    HeadingScope: pass headingLevel={3} to keep 4.x's <h3>. HeadingScope is named as Pro.
  • strings-separator (CLI-34): Formatter has two new members, separator and join, so an object you build as a
    Formatter yourself (a test double for useFormat) fails the type check until it adds them.
  • locked-not-disabled (CLI-40): the reasons the waiting controls give are 50 new locked… keys, on 31 items,
    which a translated app says in English until it translates them; the entry lists them. strings-sentences' list of
    new keys adds clarifyingQuestions.before.
  • props-active-id-nav (CLI-35): its search finds SettingsLayout's active= too.
  • The migration lines of the ten entries with a codemod name npx candor-ui@3 migrate, as the codemod lines do,
    so a project with candor-ui@2 installed doesn't run CLI 2 (CLI-37).

New items (Pro)

  • link: LinkProvider, useLink, LinkRender and LinkRenderProps. Set how Candor's items draw an address in
    the app (a Next or TanStack Link) once, or through CandorProvider's new link prop, and SessionList,
    ScopeBreadcrumb, ScopeSwitcher, PersonMenu (Help), NotificationCenter, NeedsYouLine, ScoreRing, PortfolioCard,
    DetailsList and BoardCard draw their in-app links with your router. With none set each draws the <a> it drew in
    5.0. Downloads and links to other sites stay <a>.
  • merge-refs: mergeRefs and useMergedRefs, one callback ref from an app's ref and an item's own. Tabs uses it.
  • use-settle: useSettle, which calls back once a value has stopped changing for a set time. PlanPicker and
    ScheduleEditor use it, with their 5.0 timings.
  • live-rows: LiveRows, the rows of a list whose data changes under the person, as Inbox and ApprovalQueue draw
    them (both now draw through it; the rows' list gains data-slot="live-rows", listed below).
  • email-heading: EmailHeading, EmailPreview's title at the level the page's HeadingScope gives it; a client
    part, so EmailPreview, EmailLayout and renderEmail stay free of "use client".
  • user-message-actions: UserMessageActions, Copy and Edit and send again on the person's own message, placed in
    Message's meta. Edit hands the app the message's words through onEdit; what the person sends is a new message, and
    this one stays in the thread, so the app keeps the versions. Copy appears when text is given, and Edit when both
    text and onEdit are.

Components

New, additive props (Pro):

  • ThemeSetting: choices, the looks to offer, all four by default; choices={["system", "light", "dark"]} leaves
    out High contrast. A stored value outside the list shows as nothing chosen.
  • defaultActiveId on SessionList, SidePanel, AppSidebar, TabBar, NavRail, AgentRoster, Inbox, ApprovalQueue, Plan,
    RunTree, VersionHistory, GraphView and Tree; defaultSelected on DataTable, DocumentViewer and the four charts;
    defaultOpen on RestoreDialog and ReportReply (KIT-236). Where the item had no state of its own, it keeps one only
    when the default is given; an item given neither draws as in 5.0, except Inbox and ApprovalQueue, listed above. An
    app that holds the selection itself, with undefined as none, sees none when it clears it. A chart's
    defaultSelected and Tree's defaultActiveId take null to keep the selection with none at first. DataTable keeps
    its own selection without onSelectedChange, as in 5.0; with onSelectedChange and no selected, pass
    defaultSelected (an empty Set for none) to have it tick the rows a person selects.
  • Inbox takes activeId and marks the item open beside it (KIT-234).
  • AccessRequest takes headingLevel (KIT-252). useHeadingScope(), from heading-scope, gives the nearest
    HeadingScope's level, or undefined outside one.
  • DataTable: a column with sortable: false has no sort button, no aria-sort and no place in the stacked sort control
    (KIT-221).
  • Tree's onSelect passes the node as its second argument, as the tree drew it, loaded children included;
    onSelect={(id) => …} still type-checks (KIT-239).
  • TypedText takes render, which wins over as (KIT-238).
  • DateRangeField takes name (hidden inputs {name}.from and {name}.to) and error, as DateField does (KIT-190).
  • navRailTabs takes the rail's pinned places, so more counts a pinned place left off the bar (KIT-167).
  • locked accepts null on every item, free ones (Slider) included; null or left out is unlocked (KIT-189, KIT-237).

Focus that stays put (KIT-174, KIT-175, KIT-201, KIT-245, and others). An item moves focus only when focus is inside
it, or on the control the person just used; a hold, a count or a check that arrives while the person is elsewhere is
announced instead. EnvironmentConnect, IntegrationConnect, DriftChange, NeedsYouLine and ModelKey follow it.
SessionList keeps focus on a row pinned in a virtualised list; SplitView keeps it when it narrows with the detail open;
Toast passes on the key press after a swipe-dismiss; DataTable's stacked detail closes with focus back on the card's
button; FilterChips' Clear all keeps focus in the bar (DataTable's search box); WorkflowEditor's keyboard Move ends,
announced as put back, when focus goes nowhere; DockWindow's note in place has "Go to window", the keyboard's way to
the floating window.

Locked controls: ResultButton and ProgressButton show the reason on a tap or click, as other locked controls do
(KIT-177). DataTable's column picker, FilterBar's Add button and CheckpointList's Restore keep their own alignment when
nothing locks them (KIT-241). PermissionMode gives its busy reason once (KIT-210). The gallery's Save draft is locked
with a reason, not disabled (KIT-242).

Names from the app, a model or another person (KIT-187, KIT-255): drawn inside Candor's words or in an accessible
name, their direction controls are neutralised and they are isolated in their own <bdi>: ThreadHeader, ModelPicker,
FlipCard, Calendar, AiContentLabel, CopilotPanel, PersonMenu, ScopeSwitcher, AgentRoster, McpConnect, Inbox,
ApprovalQueue, FilterChips, DataImport, ColumnMapper, CheckpointList, DocumentProgressQueue, ExtractionReview,
CommentThread, AssigneePicker, MembersTable, TestResults, DriftChange and RunTree. PersonMenu's row form draws its
initial through initialsOf (KIT-219).

Text not joined in code: IntegrationConnect and EnvironmentConnect type no spaces round the separator (KIT-240);
SsoSetup and InviteChooser join lists as the locale does ("Editor and Viewer", KIT-249); UsageMeters' value text and
RunTree's screen-reader sentence are keys with placeholders, numbers in the locale's digits (KIT-254, KIT-259); the
Premium templates draw the locale's separator, not a typed " · " (KIT-256).

The rest, by item:

  • ModelKey says "Verified with {provider}, saving…" between a passed check and stored, and its key field is a new
    password to the browser (autoComplete="new-password") (KIT-160, KIT-191).
  • ScopeSwitcher: a linked option opened in a new tab or window doesn't call onChange; a plain click calls it and
    follows the link (KIT-166). AppLayout's hideHeader="on-scroll" doc says any scroll inside <main> hides the banner
    (KIT-168).
  • Board says how many cards are in no column, and its region and group have different names (KIT-158, KIT-183).
  • DataTable: hiding the sorted column clears the sort in both forms and says so (KIT-200).
  • ColumnMapper: a suggestion with no confidence reads "Suggested" alone, with no percentage and no warning colour; the
    percentage is in the locale's digits (KIT-244).
  • RunScrubber's drag preview names the event under the pointer and stays inside the track (KIT-165). ChartFrame: a
    nested frame's caption no longer moves the plot while busy (KIT-185).
  • ToolCall draws no line counts for a negative or non-finite count, rather than "+0" (KIT-159). Composer's locked,
    empty box draws a focus ring of its own (KIT-247).
  • SliderStops reads a controlled value that is none of its stops (KIT-162); SearchInput drops a pending search when the
    app changes its value (KIT-163); DateField round-trips years under 1000 and reads Adlam digits (KIT-164);
    DrawerSwipeArea passes a tap on an icon to its button (KIT-178); FloatLabelInput lowers its label on form.reset()
    (KIT-182); DialogBody pins the header and footer inside a <form> (KIT-186); ConfirmField calls
    onMatchChange(false) when it goes while a match stands (KIT-198); Tabs' refs are stable (KIT-215).
  • GraphView puts a node back where it was when it is let go far from every place, and says so; it scrolls when a
    pointer drag nears its edge; an arrow key pressed during the settle ends it, so the node moves from where it is drawn
    (KIT-197, KIT-222, MOT-53).
  • EnvironmentList clears "Disconnected" when the environment comes back (KIT-161). IntegrationConnect's doc says a
    hold passed once connected is ignored (KIT-211). ScheduleEditor announces a change back to its first rule (KIT-184).
  • ProvenanceTrace's lines and LogStream's live dot carry their motion chain on the element that moves, so their own
    timings and a brand's values reach them (MOT-54, MOT-55). BarChart's plot carries data-plot-dir="ltr", as
    LineChart's does (MOT-58).
  • The Premium templates compile under the React Compiler (ARCH-38).

@candor-ui/react 5.1.0

  • Locked passes every key but Enter and Space (and ArrowUp and ArrowDown on a popup's trigger) to the control's own
    onKeyDown, so a locked inline TypeToConfirm can still be cancelled with Escape (KIT-176).
  • Locked under the app's TooltipProvider joins its delay group, so moving between locked controls skips the delay
    (KIT-224). useTooltipProviderAbove(), from tooltip, says whether there is one; Locked uses it.
  • ToolCall: no counts for a negative or non-finite line count (KIT-159); a finished row keeps its locked button until
    focus leaves it (KIT-245). Composer: a locked, empty box draws a focus ring (KIT-247).
  • locked accepts null (Slider). PermissionPrompt's doc shows headingLevel={3} inside a dialog (KIT-243).
  • Forced colours reach an indicator given to Progress as children (MOT-63).

Nothing to do.

Motion (Pro motion-drawings)

  • SheetContent's push drawing finds the sheet's edge by data-edge and pushes the page by the sheet's own width, with a
    Tailwind prefix and in RTL (MOT-50). A 5.0 sheet, which has no data-edge, is still found by its side's class.
  • A dialog's, sheet's or drawer's nudge keeps its ring under a family-wide attention drawing (MOT-51).
  • The typing window on <body> and GlideHighlight's travel leave out data-motion="none" and calm (MOT-56, MOT-57).
  • The row-hover drawing on a <tr> is checked in WebKit (MOT-52).
  • With expand and the ripple, an icon button's name isn't trapped under the next button (MOT-65).

CLI 3.1.0

  • migrate constructor, toString and hasOwnProperty say there is no such codemod, as any unknown name does
    (CLI-39).
  • update --differing keep keeps its copies by number inside .candor-keep/, never outside it from a monorepo path;
    update and doctor say when one is left behind (KIT-192).
  • Where it can't work out what installing an item's new dependencies writes, a plain update no longer runs shadcn's
    dry run to list it; only --differing does, since only it reads that list (KIT-225).
  • types-data rewrites export type { ToolCall as Call } to ToolCallData as Call, and the other five types (CLI-38).
  • strings-keys lists standardCards inside observer(…) or an app's own wrapper, rather than rewriting it into the
    wrong scope (CLI-42).
  • update follows a monorepo theme moved out of the shared package and recorded (CLI-41).
  • The commands update prints, and the upgrade page's, name npx candor-ui@3 (CLI-37).
  • theme check: motion-value doesn't say a keyframe-named value plays nothing where it plays (MOT-61).
  • add and update leave a dependency's specifier alone when it already satisfies the item's range, so exact pins
    stay pinned.
  • Where the project's utils alias already exports cn, add and update write no lib/utils.ts and add no cn
    package; the plan and --dry-run name every npm package before anything is written.
  • migrate headings lists <AppLayout> only with chat, and leaves out a heading whose 5.0 level is already what
    4.x drew; types-data writes MessageData, not MessageData as MessageData.
  • update and migrate strings-keys print the string keys a release adds to your installed items, under "New strings
    to translate", read from each item's strings table at both versions.
  • update names npm packages the updated items no longer import and no other recorded item needs ("No longer needed:
    cmdk"); it removes nothing.
  • --differing replace names every file it replaced, and its count matches its list.
  • A codemod says which files it didn't read (as installed, or from an older version), and migrate --verbose lists
    them.

Docs and the docs MCP

  • The docs MCP's theme_check description names motion-value (MOT-62).
  • PermissionPrompt's example shows headingLevel={3} in a dialog (KIT-243); SemanticBadge's doc names FindingData
    (KIT-257); LiveRows has an example.
  • Diagram's doc says that mermaid loads only when source is drawn, never for nodes and edges, and that it is
    still installed with the item, since the registry has no optional dependencies. Nothing changed in how it loads:
    5.0 already loaded mermaid lazily, through import(), and a test now holds it.

For maintainers

  • scripts/motion-baseline.json's entries name a problem's place (file, at, rule, and a count where there are
    several), not its words, and check:motion says which entry no longer matches (MOT-59). With 5.1's fixes it is
    empty. check:motion strips a negated running state before it decides (MOT-60), and its @ease check says a value
    it can't read can't be checked, not that it doesn't overshoot (MOT-64).
  • release:check counts the tests from its one full run (ARCH-35).
  • The 4.5.0 upgrade check moves a theme and records it, then checks the move holds (CLI-41).
  • A kit suite checks the heading rule on every item that draws a heading, from HEADING_LEFT (KIT-258).
  • The layer checks run Firefox locally too, skipping an engine that can't start with a line saying why; on CI it fails
    (KIT-213). Check M asserts the app's popupClassName on the open menu (KIT-206); contracts.mjs --list is tested
    and its header names every group (KIT-208, KIT-209); fresh-app.mjs reads the Radix app's Candor items from the
    layer page's imports (KIT-212).
  • The OrgSmith pack installs through candor-ui add, so candor-lock.json is written, and its .gitignore covers what
    the install writes (ARCH-36, ARCH-37).
  • Two test files wait on fake timers, not real time (HK-8).