# Upgrade Guide

URL: https://ark-ui.com/docs/react/overview/upgrade-guide
LLM: https://ark-ui.com/llms.txt/overview/upgrade-guide

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

---

---
id: upgrade-guide
title: Upgrade Guide
description: 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.

```sh
# 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):

| Transform | What it does |
| --- | --- |
| `carousel-props` | `slideCount` → `count`, `autoplay` → `autoPlay`, `padding` → `itemSpacing` |
| `floating-panel-placement` | `resizeTriggerAxes` → `resizeTriggerPlacements`, `axis` → `placement` |
| `image-cropper-placement` | `handles` → `placements`, `position` → `placement` |
| `tabs-virtual-focus` | `composite` → `virtualFocus` (value inverted) |
| `popover-portalled` | removes the `portalled` prop |
| `tags-input-editable` | adds `editable` to keep the old default |
| `pin-input-count` | `length` → `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](#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](#comboboxlistboxselect-gain-a-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.

```text
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.

```diff
// React
- <Collapsible.Trigger asChild>
-   <button>Toggle</button>
- </Collapsible.Trigger>
+ <Collapsible.Trigger render={(props, state) => (
+   <button {...props}>{state.open ? 'Open' : 'Closed'}</button>
+ )} />
```

```diff
// 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
<!-- Svelte -->
<Collapsible.Trigger>
  {#snippet render(props, state)}
    <button {...props()}>{state.open ? 'Open' : 'Closed'}</button>
  {/snippet}
</Collapsible.Trigger>
```

```vue
<!-- 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.

```diff
- <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.

```diff
  <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.

```diff
  <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`.

```diff
  [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.

```diff
- <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.

```diff
- [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`.

```sh
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:

| Component | v5 | v6 |
| --- | --- | --- |
| TreeView | `branch` | `node-group` |
| TreeView | `branch-control`, `item` | `node` (`[data-branch]` on branches) |
| TreeView | `branch-content`, `branch-indent-guide` | `node-group-content`, `indent-guide` |
| TreeView | `branch-indicator`, `branch-trigger` | `node-indicator`, `node-expand-trigger` |
| TreeView | `branch-text`, `item-text` | `node-text` |
| TreeView | `item-indicator` | removed; 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.

```diff
- [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`.

```diff
+ 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>
```

| v5                                   | v6                                            |
| ------------------------------------ | --------------------------------------------- |
| `count`                              | `items`                                       |
| `step` / `defaultStep`               | `value` / `defaultValue`                      |
| `onStepChange` / `onStepComplete`    | `onValueChange` / `onComplete`                |
| `isStepValid` / `isStepSkippable`    | `invalid` / `optional` on the item            |
| `onStepInvalid`                      | `onNavigationBlocked` (`reason`, `blockedBy`) |
| `index` on parts                     | `value`                                       |
| `api.setStep(index)`                 | `api.setValue(value)`                         |
| `api.isCompleted`                    | `api.complete`                                |
| `api.goToPrevStep()` / `hasPrevStep` | `api.goToPreviousStep()` / `hasPreviousStep`  |
| `Steps.ChangeDetails`                | `Steps.ValueChangeDetails`                    |
| `Steps.InvalidDetails`               | `Steps.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.

```diff
- const collator = useCollator()
- collator().compare(a, b)      // Solid, Svelte
- collator.value.compare(a, b)  // Vue
+ const collator = useCollator()
+ collator.compare(a, b)
```

```diff
- 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.

```diff
- 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.
