Repository navigation
Candor 5.1.0
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
onSelectedChangewithoutselected: a
ticked item shows ticked, and the callback is still called. In 5.0 the tick never showed. Passselectedto hold the
selection yourself: once you have passed it, the list keeps none of its own, so clearing it toundefineddraws none,
as in 5.0. - ConfirmButton (Pro) stays armed for 6 seconds by default in English (4 in 5.0): left out,
armedForis 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. PassarmedFor={4000}to keep 5.0's window; a test that waited 4
seconds for it to disarm waits for the new window or setsarmedFor. - Six data types'
lockedfield acceptsnull(string | null | undefined):PaletteItem,ScopeLevel,
SettingsItem,DashboardTileView,PermissionModeOptionandPlanAutonomyOption. Code that builds them is
unchanged; code that reads one into astring | undefinedvariable 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 newheadingLevel.
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 passesheadingLevel; a
test that found AccessRequest's title as text inside a scope finds it by roleheading. - 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.goToWindowandgoToWindowTitle.board.unplaced(one and other) andboard.columns;dataTable.sortCleared.usageMeters.amount,usedOfLimit,limitAfter,unitAfterandwithPending. The keys UsageMeters read in 5.0
are still read.runTree.readoutStatusandreadoutJoin.from,afterandverdictNoteare still read, as their placeholders.- The Premium templates' strings that held " · " (
agentOpsConsole.topLineandtopLineStopped,
approvalsInbox.owner,member,ruleHeading,waitingLineandrequestDescription,
supportCopilot.threadCustomerLineanddraftCardHeader) take{separator}, the locale's separator, in its place;
agentOpsConsole.startedByandapprovalsInbox.appliedByno longer hold it, since the template joins them. An
override that kept its own " · " instartedByorappliedByshows 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
labeland 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 newemail-headingpart. - SheetContent (Pro) carries
data-edge(top,right,bottomorleft, 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 newlive-rowspart. - A stacked Carousel (Pro): the slides' row is
aria-live="off"("polite"in 5.0), andCarouselStatushas 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: passheadingLevel={3}to keep 4.x's<h3>.HeadingScopeis named as Pro.strings-separator(CLI-34):Formatterhas two new members,separatorandjoin, so an object you build as a
Formatteryourself (a test double foruseFormat) fails the type check until it adds them.locked-not-disabled(CLI-40): the reasons the waiting controls give are 50 newlocked…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 addsclarifyingQuestions.before.props-active-id-nav(CLI-35): its search finds SettingsLayout'sactive=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 withcandor-ui@2installed doesn't run CLI 2 (CLI-37).
New items (Pro)
link:LinkProvider,useLink,LinkRenderandLinkRenderProps. Set how Candor's items draw an address in
the app (a Next or TanStackLink) once, or throughCandorProvider's newlinkprop, 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:mergeRefsanduseMergedRefs, 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 gainsdata-slot="live-rows", listed below).email-heading:EmailHeading, EmailPreview's title at the level the page'sHeadingScopegives it; a client
part, soEmailPreview,EmailLayoutandrenderEmailstay free of"use client".user-message-actions:UserMessageActions, Copy and Edit and send again on the person's own message, placed in
Message'smeta. Edit hands the app the message's words throughonEdit; what the person sends is a new message, and
this one stays in the thread, so the app keeps the versions. Copy appears whentextis given, and Edit when both
textandonEditare.
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. defaultActiveIdon SessionList, SidePanel, AppSidebar, TabBar, NavRail, AgentRoster, Inbox, ApprovalQueue, Plan,
RunTree, VersionHistory, GraphView and Tree;defaultSelectedon DataTable, DocumentViewer and the four charts;
defaultOpenon 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, withundefinedas none, sees none when it clears it. A chart's
defaultSelectedand Tree'sdefaultActiveIdtakenullto keep the selection with none at first. DataTable keeps
its own selection withoutonSelectedChange, as in 5.0; withonSelectedChangeand noselected, pass
defaultSelected(an emptySetfor none) to have it tick the rows a person selects.- Inbox takes
activeIdand marks the item open beside it (KIT-234). - AccessRequest takes
headingLevel(KIT-252).useHeadingScope(), fromheading-scope, gives the nearest
HeadingScope's level, orundefinedoutside one. - DataTable: a column with
sortable: falsehas no sort button, noaria-sortand no place in the stacked sort control
(KIT-221). - Tree's
onSelectpasses 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 overas(KIT-238). - DateRangeField takes
name(hidden inputs{name}.fromand{name}.to) anderror, as DateField does (KIT-190). navRailTabstakes the rail'spinnedplaces, somorecounts a pinned place left off the bar (KIT-167).lockedacceptsnullon every item, free ones (Slider) included;nullor 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'shideHeader="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 onform.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
holdpassed 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 carriesdata-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
Lockedpasses 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).Lockedunder the app'sTooltipProviderjoins its delay group, so moving between locked controls skips the delay
(KIT-224).useTooltipProviderAbove(), fromtooltip, 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). lockedacceptsnull(Slider). PermissionPrompt's doc showsheadingLevel={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-edgeand pushes the page by the sheet's own width, with a
Tailwind prefix and in RTL (MOT-50). A 5.0 sheet, which has nodata-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 outdata-motion="none"and calm (MOT-56, MOT-57). - The row-hover drawing on a
<tr>is checked in WebKit (MOT-52). - With
expandand the ripple, an icon button's name isn't trapped under the next button (MOT-65).
CLI 3.1.0
migrate constructor,toStringandhasOwnPropertysay there is no such codemod, as any unknown name does
(CLI-39).update --differing keepkeeps its copies by number inside.candor-keep/, never outside it from a monorepo path;
updateanddoctorsay when one is left behind (KIT-192).- Where it can't work out what installing an item's new dependencies writes, a plain
updateno longer runs shadcn's
dry run to list it; only--differingdoes, since only it reads that list (KIT-225). types-datarewritesexport type { ToolCall as Call }toToolCallData as Call, and the other five types (CLI-38).strings-keyslistsstandardCardsinsideobserver(…)or an app's own wrapper, rather than rewriting it into the
wrong scope (CLI-42).updatefollows a monorepo theme moved out of the shared package and recorded (CLI-41).- The commands
updateprints, and the upgrade page's, namenpx candor-ui@3(CLI-37). theme check:motion-valuedoesn't say a keyframe-named value plays nothing where it plays (MOT-61).addandupdateleave a dependency's specifier alone when it already satisfies the item's range, so exact pins
stay pinned.- Where the project's
utilsalias already exportscn,addandupdatewrite nolib/utils.tsand add nocn
package; the plan and--dry-runname every npm package before anything is written. migrate headingslists<AppLayout>only withchat, and leaves out a heading whose 5.0 level is already what
4.x drew;types-datawritesMessageData, notMessageData as MessageData.updateandmigrate strings-keysprint 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.updatenames npm packages the updated items no longer import and no other recorded item needs ("No longer needed:
cmdk"); it removes nothing.--differing replacenames 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 --verboselists
them.
Docs and the docs MCP
- The docs MCP's
theme_checkdescription namesmotion-value(MOT-62). - PermissionPrompt's example shows
headingLevel={3}in a dialog (KIT-243); SemanticBadge's doc namesFindingData
(KIT-257); LiveRows has an example. - Diagram's doc says that
mermaidloads only whensourceis drawn, never fornodesandedges, 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 loadedmermaidlazily, throughimport(), and a test now holds it.
For maintainers
scripts/motion-baseline.json's entries name a problem's place (file,at,rule, and acountwhere there are
several), not its words, andcheck:motionsays which entry no longer matches (MOT-59). With 5.1's fixes it is
empty.check:motionstrips a negated running state before it decides (MOT-60), and its@easecheck says a value
it can't read can't be checked, not that it doesn't overshoot (MOT-64).release:checkcounts 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'spopupClassNameon the open menu (KIT-206);contracts.mjs --listis tested
and its header names every group (KIT-208, KIT-209);fresh-app.mjsreads the Radix app's Candor items from the
layer page's imports (KIT-212). - The OrgSmith pack installs through
candor-ui add, socandor-lock.jsonis written, and its.gitignorecovers what
the install writes (ARCH-36, ARCH-37). - Two test files wait on fake timers, not real time (HK-8).