Upgrade Guide

What changed in Ark UI v6, and the breaking changes to fix as you migrate.

v6 keeps the components you already know and unifies how you compose them. Polymorphism moves to a single render function, every part forwards its machine state, and the frameworks line up so the same anatomy works across React, Solid, Svelte, and Vue. This guide covers the breaking changes and how to migrate.

Automated migration

Most of the mechanical work ships as codemods. Run list to see every transform, then run the ones you need against your files.

# See every available transform
npx @ark-ui/codemod list

# Preview the changes without writing them
npx @ark-ui/codemod react/as-child-to-render "src/**/*.tsx" --dry

--dry prints a diff and writes nothing. Without it the codemod refuses to run on a dirty working tree, so a bad run is one git checkout away. Anything ambiguous is left untouched and reported with a file and a reason rather than guessed.

Only Ark UI elements are rewritten — an asChild from another library in the same file is left alone. Parts reached through local barrels, re-exports, or factory wrappers (styled(ark.button)) are resolved with the --cross-file flag.

Beyond as-child-to-render, prop renames ship for every framework — react/*, solid/*, svelte/*, and vue/* (Vue rewrites kebab and bound props too):

TransformWhat it does
carousel-propsslideCount → count, autoplay → autoPlay, padding → itemSpacing
floating-panel-placementresizeTriggerAxes → resizeTriggerPlacements, axis → placement
image-cropper-placementhandles → placements, position → placement
tabs-virtual-focuscomposite → virtualFocus (value inverted)
popover-portalledremoves the portalled prop
tags-input-editableadds editable to keep the old default
pin-input-countlength → count, or flags a missing count

Data-attribute selectors, in stylesheets, components or JS/TS, have their own transform, css/data-attributes, covered under Data attributes are merged below.

Two changes are left to do by hand because they reshape markup, not just props: the popover api.portalled ? Portal : Fragment wrapper (drop it for a plain Portal), and the Combobox/Listbox/Select content → content + list split described under the list part.

Migrate with an AI agent

The codemod handles asChild → render. For the rest, paste this prompt into an AI agent (Claude Code, Cursor, Copilot) pointed at your codebase — it has the full context for the manual changes.

You are migrating this codebase from Ark UI v5 to v6. Work framework-aware
(React, Solid, Svelte, or Vue — detect which one this project uses) and change
only Ark UI usage. After each step, run the project's typecheck/build.

1. Run the codemod for the mechanical rename, then review its report:
   npx @ark-ui/codemod react/as-child-to-render "src/**/*.tsx"
   (swap `react` for solid/svelte/vue; add `--cross-file` if parts are reached
   through local barrels, re-exports, or factory wrappers like styled(ark.button).)

2. Finish anything the codemod left. `asChild` is now a `render` function that
   receives (props, state):
   - React/Vue: move the child into the function/slot; spread `props`.
   - Solid/Svelte/Vue: `props` is a MERGE FUNCTION — spread `{...props()}`
     (Solid/Svelte) or `v-bind="props()"` (Vue), and call `props({ onClick })`
     to merge your handlers instead of overwriting them. In Solid, `state` is an
     accessor: `state().open`.

3. Toaster is no longer polymorphic: remove any `render`/`asChild` on it and
   drop `ToasterState`. Style the group with CSS (`data-placement`, `data-side`,
   `data-align`) or wrap your own element around it.

4. Combobox.Empty / Listbox.Empty move OUT of List to become a sibling of List.
   Put the styled message in a child element. For loading/error states, use the
   new `Status` part on Combobox, Listbox, and Select.

5. Indicator and control parts inside a button or label now render `span`, not
   `div`: Accordion.ItemIndicator, Collapsible.Indicator, Popover.Indicator,
   Toggle.Indicator, Select.Indicator/ItemIndicator, Combobox.ItemIndicator,
   Listbox.ItemIndicator, Menu.Indicator/ItemIndicator,
   NavigationMenu.ItemIndicator, Checkbox.Control/Indicator,
   RadioGroup.ItemControl, SegmentGroup.ItemControl, Clipboard.Indicator,
   Steps.Indicator, Splitter.ResizeTriggerIndicator, Avatar.Root,
   Tabs.Indicator, NumberInput.Scrubber. Add an explicit `display` wherever
   styles assumed a block (sizes, transforms). React refs become HTMLSpanElement.

6. TagsInput is no longer editable by default. Add `editable` wherever tags
   should still open for editing on double-click.

7. useCollator / useFilter now return values directly (no accessor/.value) on
   Solid, Svelte, and Vue: `collator.compare(a, b)`, `const { contains } = useFilter(...)`.

8. Svelte only:
   - The `useX` hooks now require an `id`: `useCollapsible({ id })` where
     `const id = $props.id()`. `$props.id()` may be called once — derive if you
     need two. Components like `<Collapsible.Root>` are unaffected.
   - Exports now match the other frameworks: Dialog parts are prefixed
     (`DialogPositioner`, `DialogRoot`, ...); `StepsStepChangeDetails` →
     `StepChangeDetails`, `ColorPickerColor` → `Color`, `TabsContentState` /
     `TabsTriggerState` → `TabContentState` / `TabTriggerState`. Internals like
     `CheckboxProvider` and `splitCollapsibleProps` are no longer exported.

Report anything ambiguous instead of guessing. Full guide:
https://ark-ui.com/docs/overview/upgrade-guide

Breaking changes to fix

These are the changes you have to act on when you move a project from v5.

asChild is now render

Polymorphism moves from a wrapper prop to a render function that receives the part's props and its state. Every part gets one typed composition API, and you can read machine state inline.

The shape differs per framework. React and Vue move the child into the function or slot; Solid and Svelte are a rename where the props object becomes a props function you must call.

// React
- <Collapsible.Trigger asChild>
-   <button>Toggle</button>
- </Collapsible.Trigger>
+ <Collapsible.Trigger render={(props, state) => (
+   <button {...props}>{state.open ? 'Open' : 'Closed'}</button>
+ )} />
// Solid — {...props} becomes {...props()}, state is an accessor
- <Collapsible.Trigger asChild>
-   {(props) => <button {...props}>Toggle</button>}
- </Collapsible.Trigger>
+ <Collapsible.Trigger render={(props, state) => (
+   <button {...props()}>{state().open ? 'Open' : 'Closed'}</button>
+ )} />
<!-- Svelte -->
<Collapsible.Trigger>
  {#snippet render(props, state)}
    <button {...props()}>{state.open ? 'Open' : 'Closed'}</button>
  {/snippet}
</Collapsible.Trigger>
<!-- Vue -->
<Collapsible.Trigger>
  <template #render="{ props, state }">
    <button v-bind="props()">{{ state.open ? 'Open' : 'Closed' }}</button>
  </template>
</Collapsible.Trigger>

In Solid, Svelte, and Vue, props is a merge function: call props({ onClick: mine }) to merge your handlers with the part's instead of overwriting them.

Toaster is no longer polymorphic

Toaster no longer accepts render or asChild, and ToasterState is gone. Its children belong to the machine, so handing them over dropped toasts. Style the group with CSS — it carries data-placement, data-side, and data-align — or wrap your own element around Toaster.

Popover is no longer portalled by prop

The portalled prop and api.portalled value are gone. The popover now detects whether its content is portalled from where you render it and proxies tab order accordingly, so a forgotten portalled can no longer break keyboard access. Decide portalling by rendering the content inside Portal or not.

- <Popover.Root portalled>
+ <Popover.Root>
    <Popover.Trigger>Open</Popover.Trigger>
+   <Portal>
      <Popover.Positioner>
        <Popover.Content>...</Popover.Content>
      </Popover.Positioner>
+   </Portal>
  </Popover.Root>

The react/popover-portalled codemod (and its solid/svelte/vue variants) removes the prop; wrap the content in Portal yourself, as this is markup the codemod won't reshape. To render inline, drop the Portal — tab order is still handled.

Combobox.Empty and Listbox.Empty move out of List

Empty used to render inside List and unmount when the collection was non-empty, which kept it out of the accessibility tree and prevented any announcement. It now stays mounted as a sibling of List with role="status", swapping only its children. Move it out of List and put your styled message in a child element.

  <Combobox.Content>
-   <Combobox.List>
-     <Combobox.Empty className={styles.Item}>No results found</Combobox.Empty>
+   <Combobox.Empty>
+     <div className={styles.Empty}>No results found</div>
+   </Combobox.Empty>
+   <Combobox.List>
      {/* items */}
    </Combobox.List>
  </Combobox.Content>

A new Status part on Combobox, Listbox, and Select covers loading and error states that Empty cannot distinguish (it keys off collection.size === 0).

Combobox/Listbox/Select gain a List part

The listbox semantics (role="listbox", active-descendant, keyboard focus) move off Content onto a new List part. Content becomes a plain wrapper, so you can render headers, footers, or a search input in the popup without polluting the listbox. Wrap the items in List inside Content. This is structural, so the codemod leaves it to you.

  <Combobox.Content>
+   <Combobox.List>
      {items.map((item) => (
        <Combobox.Item key={item.value} item={item}>{item.label}</Combobox.Item>
      ))}
+   </Combobox.List>
  </Combobox.Content>

The composite prop is gone; pass popupType="dialog" where you previously set composite={false}.

Indicator and control parts render span

Indicator and control parts that sit inside a button or label now render span instead of div. A div there is invalid HTML, since both only accept phrasing content. The affected parts:

  • Accordion.ItemIndicator, Collapsible.Indicator, Popover.Indicator, Toggle.Indicator
  • Select.Indicator, Select.ItemIndicator, Combobox.ItemIndicator, Listbox.ItemIndicator
  • Menu.Indicator, Menu.ItemIndicator, NavigationMenu.ItemIndicator
  • Checkbox.Control, Checkbox.Indicator, RadioGroup.ItemControl, SegmentGroup.ItemControl
  • Clipboard.Indicator, Steps.Indicator, Splitter.ResizeTriggerIndicator
  • Avatar.Root, Avatar.RootProvider, Tabs.Indicator, NumberInput.Scrubber

A span is inline, so width, height and transform stop applying to it. If your styles relied on the part being a block, a rotating accordion indicator for example, give it an explicit display.

  [data-accordion-item-indicator] {
+   display: inline-flex;
    transition: transform 0.2s;
  }

In React, refs to these parts are now typed HTMLSpanElement.

TagsInput is no longer editable by default

Tags no longer open for editing on double-click unless you pass editable. The react/tags-input-editable codemod (and its solid/svelte/vue variants) adds it for you; without the codemod, add it wherever tags should stay editable.

- <TagsInput.Root>
+ <TagsInput.Root editable>

Data attributes are merged

data-scope, data-part, and data-ownedby collapse into one attribute per part, data-{scope}-{part}. An element can now take part in more than one machine, and selectors get shorter. This does not change your JSX — it changes the CSS and any querySelector that targets these attributes.

- [data-scope="dialog"][data-part="trigger"] { ... }
+ [data-dialog-trigger] { ... }

The css/data-attributes transform rewrites stylesheets, Vue and Svelte <style> blocks, and the selectors in JS/TS files (style objects, CSS-in-JS template literals, querySelector strings): it merges scope/part selectors, turns toggle [data-state="on"] into [data-pressed], and swaps the removed data-focus on toggle-group and toolbar for :focus-within / :focus-visible.

npx @ark-ui/codemod css/data-attributes "src/**/*.{css,ts,tsx,vue,svelte}" --dry

Selectors where scope and part are not adjacent, that use escaped quotes, or that are built from variables are left for you to update. Outside .css files, [data-state="on"] only becomes [data-pressed] right after a toggle or toggle-group item selector, so other libraries' selectors stay as they are.

A few attributes changed name, and the codemod leaves these for you:

Componentv5v6
TreeViewbranchnode-group
TreeViewbranch-control, itemnode ([data-branch] on branches)
TreeViewbranch-content, branch-indent-guidenode-group-content, indent-guide
TreeViewbranch-indicator, branch-triggernode-indicator, node-expand-trigger
TreeViewbranch-text, item-textnode-text
TreeViewitem-indicatorremoved; use node-indicator
ImageCropper handle[data-position="nw"], …[data-placement="nw"], …
FloatingPanel resize trigger[data-axis="n"], …[data-placement="n"], …

JsonTreeView also drops its own scope: v5 parts carried data-scope="json-tree-view", and v6 parts use the tree view's attributes, so [data-scope="json-tree-view"][data-part="branch"] becomes [data-tree-view-node-group], not [data-json-tree-view-branch].

Steps also keeps a step completed when the user goes back to it, so a step can carry both data-current and data-complete. Put your current-step style after the completed one, or scope the completed style with :not([data-current]).

Overlays no longer set a z-index

Popover, Menu, Select, Combobox, Tooltip, HoverCard, DatePicker, ColorPicker, Dialog, Drawer, Tour, FloatingPanel and Toast no longer put an inline z-index on their content. A z-index you set on the content now loses to its positioner, and overlays could drop behind each other while animating out.

Set the z-index on the positioner (or the backdrop) in CSS. Each one exposes --layer-index, its place in the stack of open layers, so nested overlays stay on top of their parent.

- [data-popover-content] {
-   z-index: 1400;
- }
+ [data-popover-positioner] {
+   z-index: calc(1400 + var(--layer-index));
+ }
  • Dialog and Drawer no longer set --z-index. Use --layer-index on the backdrop and positioner.
  • FloatingPanel: style the positioner the same way to bring the focused panel to the front.
  • Tour no longer copies the content's z-index onto dialog steps. Style the positioner with --tour-layer.
  • Toast: set the z-index on [data-toast-group].

Steps takes items and addresses steps by value

Steps are defined by an items array and addressed by a string value instead of a count and an index. Each item can be optional, invalid, disabled or editable, and can carry a title and a description.

+ const items = [{ value: 'shipping' }, { value: 'gift', optional: true }, { value: 'payment' }]

- <Steps.Root count={3} defaultStep={0} onStepChange={(details) => setStep(details.step)}>
+ <Steps.Root items={items} defaultValue="shipping" onValueChange={(details) => setStep(details.value)}>
    <Steps.List>
-     <Steps.Item index={0}>
+     <Steps.Item value="shipping">
        <Steps.Trigger>Shipping</Steps.Trigger>
      </Steps.Item>
    </Steps.List>
-   <Steps.Content index={0}>...</Steps.Content>
+   <Steps.Content value="shipping">...</Steps.Content>
    <Steps.CompletedContent>Done</Steps.CompletedContent>
  </Steps.Root>
v5v6
countitems
step / defaultStepvalue / defaultValue
onStepChange / onStepCompleteonValueChange / onComplete
isStepValid / isStepSkippableinvalid / optional on the item
onStepInvalidonNavigationBlocked (reason, blockedBy)
index on partsvalue
api.setStep(index)api.setValue(value)
api.isCompletedapi.complete
api.goToPrevStep() / hasPrevStepapi.goToPreviousStep() / hasPreviousStep
Steps.ChangeDetailsSteps.ValueChangeDetails
Steps.InvalidDetailsSteps.NavigationBlockedDetails

Steps.SkipTrigger skips an optional step, and completedValues makes the completed steps controllable. In Vue, v-model holds the current step's value (it was v-model:step). In Svelte, bind value (it was bind:step). The --percent variable on the progress part is now --steps-percent.

useCollator and useFilter return values

For Solid, Svelte, and Vue, these hooks now return their values directly instead of an accessor, matching React. They still follow locale changes.

- const collator = useCollator()
- collator().compare(a, b)      // Solid, Svelte
- collator.value.compare(a, b)  // Vue
+ const collator = useCollator()
+ collator.compare(a, b)
- const filters = useFilter({ sensitivity: 'base' })
- filters().contains(text, query)     // Solid, Svelte
- filters.value.contains(text, query) // Vue
+ const { contains } = useFilter({ sensitivity: 'base' })
+ contains(text, query)

Svelte: hooks require an id

After moving to Zag 2, the useX hooks require an id. Without one, two instances on a page generated the same element ids. Components (<Collapsible.Root>) are unaffected and still mint their own.

- const collapsible = useCollapsible()
+ const id = $props.id()
+ const collapsible = useCollapsible({ id })

$props.id() may only be called once per component; derive from it if you need two.

Svelte: export parity

Svelte exports now match the other frameworks. Dialog's Positioner, Root, RootProvider, Title, and Trigger are prefixed (DialogPositioner). StepsStepChangeDetails → StepsValueChangeDetails (see Steps above), ColorPickerColor → Color, TabsContentState / TabsTriggerState → TabContentState / TabTriggerState. Internals such as CheckboxProvider and splitCollapsibleProps are no longer exported.