---
title: "Migration to v2"
description: "A comprehensive guide to migrate your application from Bitrix24 UI v1 to Bitrix24 UI v2."
canonical_url: "https://bitrix24.github.io/b24ui/docs/getting-started/migration"
---
# Migration to v2

> A comprehensive guide to migrate your application from Bitrix24 UI v1 to Bitrix24 UI v2.

> [!NOTE]
> Bitrix24 UI v2 requires **Nuxt 4** due to some dependencies. Make sure to upgrade to Nuxt 4 before migrating to Bitrix24 UI v2.

This guide provides step-by-step instructions to migrate your application to Bitrix24 UI v2.

## Changes

After upgrading to Bitrix24 UI v2, please note the following important changes:

### Renamed ButtonGroup

The `ButtonGroup` component has been renamed to [`FieldGroup`](https://bitrix24.github.io/b24ui/raw/docs/components/field-group.md):

```diff
<template>
- <B24ButtonGroup>
+ <B24FieldGroup>
    <B24Button label="Button" />
    <B24Button use-dropdown />
+ </B24FieldGroup>
- </B24ButtonGroup>
</template>
```

### Renamed model modifiers

The `modelModifiers` shape used by [`Input`](https://bitrix24.github.io/b24ui/raw/docs/components/input.md), [`InputNumber`](https://bitrix24.github.io/b24ui/raw/docs/components/input-number.md) and [`Textarea`](https://bitrix24.github.io/b24ui/raw/docs/components/textarea.md) has changed in v2:

1. The `nullify` modifier was renamed to `nullable` (it converts empty/blank values to `null`).
2. A new `optional` modifier was added (it converts empty/blank values to `undefined`).

```diff
- <B24Input v-model.nullify="value" />
+ <B24Input v-model.nullable="value" />
```

```diff
- <B24Textarea v-model="value" :model-modifiers="{ nullify: true }" />
+ <B24Textarea v-model="value" :model-modifiers="{ nullable: true }" />
```

Use `nullable` when you want empty values as `null`, and `optional` when you prefer `undefined` for absent values.

### Changes to Form component

The `Form` component has been improved in v2 with better state management and nested form handling. Here are the key changes you need to be aware of:

1. Schema **transformations will only** be applied to the **@submit data** and will no longer mutate the form's state. This provides better predictability and prevents unexpected state mutations.
2. **Nested forms must be enabled explicitly** using the `nested` prop. This makes the component behavior more explicit and prevents accidental nested form creation.
3. **Nested forms should now provide a name** prop (similar to `B24FormField`) and will automatically inherit their state from their parent form.

```diff
<template>
  <B24Form :state="state" :schema="schema" @submit="onSubmit">
    <B24FormField label="Customer" name="customer">
      <B24Input v-model="state.customer" placeholder="Wonka Industries" />
    </B24FormField>

    <div v-for="(item, index) in state.items" :key="index">
      <B24Form
-       :state="item"
+       :name="`items.${index}`"
        :schema="itemSchema"
+       nested
      >
        <B24FormField :label="!index ? 'Description' : undefined" name="description">
          <B24Input v-model="item.description" />
        </B24FormField>
        <B24FormField :label="!index ? 'Price' : undefined" name="price">
          <B24Input v-model="item.price" type="number" />
        </B24FormField>
      </B24Form>
    </div>
  </B24Form>
</template>
```

### useSidebarLayout removed

Composable `useSidebarLayout` is no longer supported.

Support for the loading state of the [SidebarLayout](https://bitrix24.github.io/b24ui/raw/docs/components/sidebar-layout.md) component via [DashboardGroup](https://bitrix24.github.io/b24ui/raw/docs/components/dashboard-group.md) will be added in an upcoming release.

### @bitrix24/b24style removed

The [Bitrix24 UI](https://github.com/bitrix24/b24ui/tree/main/src/runtime/air-design-tokens) styles are now responsible for styling.

We've tried to maintain compatibility, but if any issues arise, please [let us know](https://github.com/bitrix24/b24ui/issues).

## Sitemap

See the full [sitemap](/b24ui/sitemap.md) for all pages.