Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
198 changes: 198 additions & 0 deletions docs/content/docs/1.getting-started/3.migration/2.v3.md
Original file line number Diff line number Diff line change
Expand Up @@ -399,6 +399,204 @@ This change affects the following components: `Modal`, `Slideover`.
+ <USelectMenu v-model="country" :items="countries" @update:modelValue="console.log(newVal)" />
```

#### Accordion
The `Accordion` component has been hugely redesigned to provide a clearer state model, improved accessibility, and more flexible customization. As a result, its API is not fullybackward compatible.

Below are the most important changes to migrate existing usage.

- The `multiple` prop has been replaced by the `type` prop:

```diff
<template>
- <UAccordion multiple :items="items" />
+ <UAccordion type="multiple" :items="items" />
</template>
```
When omitted, `type` defaults to `single`.

- The `default-open` prop and `defaultOpen` **item** property have been removed.

Accordion state is now controlled using default-value (uncontrolled) or v-model (controlled):

```diff
<template>
- <UAccordion default-open multiple :items="items" />
+ <UAccordion
+ type="multiple"
+ :default-value="['0', '1']"
+ :items="items"
+ />
</template>
```

- The slot API has been simplified and made more explicit.
The `#item` slot has been removed in favor of `#content` and `#body`:

```diff
<template>
- <template #item="{ item }">
- {{ item.content }}
- </template>

+ <template #content="{ item }">
+ {{ item.content }}
+ </template>
</template>
```

::note
The default slot now only customizes the trigger, with additional slots for finer control (`#leading`, `#trailing`, `#body`).
::

::note
The Accordion now follows a controlled / uncontrolled pattern (v-model / default-value) and introduces a more structured slot and styling system.
Refer to the Accordion documentation for full details and advanced use cases.
::


#### Table
The `Table` component had a major redesign, as it now uses the [TanStack Table](https://tanstack.com/table/latest){target="_blank" rel="noopener"} under the hood. This resulted in an almost new API and some breaking changes, but with many great features along the way.

Below are the most important changes to migrate existing usage.

- The `rows` prop has been renamed in favbor of `data`:

```diff
<template>
- <UTable :rows="items" :columns="headers" />
+ <UTable :data="items" :columns="headers" />
</template>
```

- Columns definition is now explicit & semantic:

```diff
<script setup lang="ts">
- const headers = {
- label: 'Status',
- key: 'status'
- }
+ const headers = [
+ {
+ header: 'Status',
+ accessorKey: 'status'
+ }
+ ]
</script>
```

- Row cell slot names has been changed from `<column-accessorKey>-data` to `<column-accessorKey>-cell`:

```diff
<template>
- <template #column-data="{ row }">
+ <template #column-cell="{ row }">
</template>
```

- Slots receive a row wrapper, not the raw object, augmented with differnet properties:

```diff
<template>
- row.status
+ row.original.status
</template>
```

::note
Every slot using row.xxx must switch to row.original.xxx
::

::note
Those are only some of the many breaking changes, refer to the Table documentation for full details and advanced use cases.
::


#### Tabs

- The `#item` slot has been removed in favor of `#content`

```diff
<template>
- <template #item="{ item }">
+ <template #content="{ item }">
</template>
```

::note
There are now other slots including `leading`, `trailing`, `list-leading` and `list-trailing`. Kindly refers to the Tabs documentation for full details and examples
::

- The prop `defaultIndex` has been removed in favor of `defaultValue` that takes the new `value` prop in `items[]`, that v-model now binds to it.

```diff
<template>
- <UTabs :default-index="0" :items="tabs" />
+ <UTabs :default-value="0" :items="tabs" />
</template>
```

::note
The `value?` prop could be `string` | `number` and it's a unique value for the tab item. Defaults to the index.
::

- The prop `unmount` has been removed in favor of `unmountOnHide`, that's when set to `true`, the element will be unmounted on closed state.
Defaults to `true`.

```diff
<template>
- <UTabs umount :items="tabs" />
+ <UTabs :unmount-on-hide="true" :items="tabs" />
</template>
```

#### Alert

- The `close-button` prop has been replaced by the `close` prop:
```diff
<template>
- <UAlert :close-button="{ icon: 'i-heroicons-x-mark', variant: 'link' }" />
+ <UAlert :close="{ icon: 'i-lucide-x', variant: 'link' }" />
</template>
```

- The `close` event has been replaced by the `update:open` event:

```diff
<template>
- <UAlert @close="isOpen = false" />
+ <UAlert @update:open="isOpen = false" />
</template>
```

- The `#icon` and `#avatar` slots have been replaced by a single `#leading` slot:

```diff
<template>
- <UAlert>
- <template #icon>
- <UIcon name="i-heroicons-command-line" />
- </template>
- </UAlert>

+ <UAlert>
+ <template #leading>
+ <UIcon name="i-lucide-terminal" />
+ </template>
+ </UAlert>
</template>
```


- `Form` now always validates on submit, as a result the `validate-on` prop only controls which input events triggers validation, that besides the default form validation on submit, so if you want the `Form` to validate only on sibmit, you need to pass an empty array to `validate-on`

```diff
<template></template>
- <UForm :validate-on="['submit']" />
+ <UForm :validate-on="[]" />
</template>
```

### Changed composables

- The `useToast()` composable `timeout` prop has been renamed to `duration`:
Expand Down
Loading