Migration to 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:

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

Renamed model modifiers

The modelModifiers shape used by Input, InputNumber and Textarea 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).

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

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

<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 component via DashboardGroup will be added in an upcoming release.

@bitrix24/b24style removed

The Bitrix24 UI styles are now responsible for styling.

We've tried to maintain compatibility, but if any issues arise, please let us know.