Developing UI Components with Bitrix24 UI Kit (React)

Bitrix24 UI Component Development: Where the Interface Breaks

The Bitrix24 portal interface doesn't break at the layout stage, but at the junction of logic: the same data block is rendered by three different components, each with its own copy of display rules.

You make an edit in one — the other two keep showing the old state, and the user sees a discrepancy in the deal card or feed. This is a classic desync that accumulates over months and manifests as "sometimes it works, sometimes it doesn't."

Duplicating logic hits support harder than it seems. When a filter, pagination, and access rights are duplicated across custom components, any change to a business rule has to be made separately in each place.

Miss one — and you get different behavior for similar screens and a queue of tasks to "fix it here too."

A separate category of problems is compatibility with core updates. The portal updates, contracts and data structures change, and custom components tied to internal details stop receiving correct values.

On the surface it looks like "the layout broke," but in fact it's a broken Bitrix24 interface at the data exchange level.

We break down such interfaces layer by layer: where the common data source is, where the reusable component is, where there's room for extension without modifying the core. Next — how this is handled in practice.

What a reusable component library delivers

A reusable library is not a "folder of buttons" but a fixed contract between design and development. Each component describes its behavior once: loading and error states, focus, keyboard navigation, responsive breakpoints, handling of long texts and empty data.

From then on, the interface is assembled from ready-made blocks, and a new section of the portal or personal account appears in days rather than weeks — the speed of interface assembly grows many times over, because the engineer does not rewrite the table, form, and modal window for every task.

A unified UI kit eliminates an entire class of layout errors, not individual bugs. When markup, spacing, and overflow behavior are defined in one place, discrepancies between pages disappear by definition: a fix in a component is applied immediately in all places of use.

This also removes typical defects — "it broke on a narrow screen," "the button is inactive but clickable," "the tooltip overlaps the field" — there is simply nowhere to reproduce them again.

A separate effect is predictable maintenance. A change in interface requirements turns into a pinpoint edit of a component and an update of the library version, rather than a revision of dozens of templates.

We version the kit, keep a changelog, and maintain backward compatibility, so an update does not break already working sections, and rolling back to a previous version takes minutes.

For the client, this translates into three measurable things: reduced time to assemble a new interface, a lower share of edits returning from testing and acceptance, and a smaller volume of code that needs to be maintained.

The library pays for itself by the second or third task, where the interface is assembled from already-tested blocks rather than from scratch.

Approaches to building the UI layer: comparing options

The UI layer in Bitrix24 is assembled on top of React, but the choice of component library determines how much time maintenance will take and how the interface will behave during platform updates.

Below are three working alternatives that are realistically chosen between at the start of a project, along with their limitations.

Custom UI kit

Full control over markup, behavior, and theming: components are written for specific portal scenarios, without unnecessary dependencies. Suitable when the interface is a competitive advantage and there is a team ready to maintain the library.

The limitation is the cost of ownership: documentation, regression tests, accessibility and responsive support fall on you, not the vendor.

Ready-made UI Kit

Fast start: typical tables, forms, modals, and notifications are already assembled and covered with states. Suitable for internal portals and tasks where speed of delivery matters, not unique presentation.

The limitation is the boundaries of the design system: non-standard scenarios will have to be worked around, and major library updates sometimes drag changes into your code.

Hybrid layer

Base elements are taken from a ready-made set, while unique blocks are written in-house — with a shared layer of tokens and themes. Suitable for most projects: speed at the start and freedom where it adds value.

The limitation is that discipline is required: without unified rules on theming and composition, a hybrid quickly turns into a zoo of two incompatible styles.

In practice, the choice comes down to who is responsible for maintenance a year from now and how much the interface differs from the typical one. Describe your portal scenarios — we'll come back with an estimate and a plan for the UI layer.

How we develop Bitrix24 UI components

Development of UI components for Bitrix24 starts not with code, but with an inventory of what already exists in the interface.

We look at which blocks repeat across different pages, where logic is smeared across templates, and where a component drags along unnecessary dependencies. The output is a reuse map: which elements become shared and which remain local.

Next, we lock down the contract of each component before implementation. This is a key stage: if the API is designed around the current page, in a month it will have to be broken.

1. Interface audit. We compile a registry of existing blocks and find duplicates and inconsistencies in behavior. We note what is reused and what is unique to a section.
2. Designing the component API. We define input parameters, events, slots, and states (loading, empty result, error). We agree on the contract with those who will be integrating the component.
3. Implementation. We write components in isolation, with local styles and without global selectors, so that embedding on one page does not break neighboring ones.
4. Compatibility check. We run the components across different themes and at different resolutions, and check behavior with real portal data rather than stubs.
5. Integration into pages. We replace old blocks one at a time, keeping the section functional at every step — without a "big switchover."
6. Handover and documentation. We provide parameter descriptions, integration examples, and extension rules so that the client's team can add variants without us.

The order matters: the audit and API design take more time than it seems, but they are exactly what eliminates rework at the integration stage.

Once the contract is locked down, implementation and compatibility checks proceed predictably, and handover comes down to documenting decisions already made.

What we hand over to the client: artifacts and documentation

We hand over not a "folder with files," but a complete set that the client's team can use to work without us. Each artifact addresses its own class of tasks: some are needed for development, others for design and support.

• Component source code — a repository with change history, not an archive. Each component is isolated, builds separately, and plugs into the project without modifying neighboring modules.
• Design tokens — colors, spacing, typography, radii, and states are moved into a separate layer. Changing a value in a token changes the appearance of all components at once, without going through files.
• UI kit documentation — a description of the properties, variants, and constraints of each component. A developer sees which states are supported and doesn't invent workarounds.
• Live component catalog — a stand where each element is shown in all states: default, hover, focus, disabled. It serves both as a showcase and as a regression check during updates.
• Update policy — the procedure for when a new version of the library is released: what we check, how we record incompatibilities, how we roll back to the previous set.
• Integration guide — how to set up the build from scratch, which dependencies are needed, how to add a new component to the shared set.
• Responsibility map — which components we maintain, which transfer to the client's team, and where the boundary of edits lies.

We separately define naming rules and folder structure — this is what determines whether the kit will live on after us or turn into a dump in six months. Documentation and update policies are updated together with the code, not as a separate "someday" effort.

Describe your task — we'll come back with an estimate and a plan for the composition of artifacts for your project.

Case study: unifying the portal interface across 40+ pages

The corporate portal on Bitrix24 grew organically: each department commissioned its own pages, and by the time of the audit, 40+ sections housed four different sets of buttons, three palettes, and their own form styles.

Edits had to be made in each template separately, and any change to the corporate style turned into a multi-day walkthrough of all pages.

What it was before

Assembling an interface took 3-4 days per typical page: a markup developer built the form, a designer checked the spacing, a developer wired up the logic. Layout errors surfaced already in production — grid and button state discrepancies were found on 6-8 out of 10 pages.

Rolling out new functionality dragged on: while the appearance was being approved, the requirements changed.

What we changed

Our engineers built an internal UI component library on Bitrix24 UI Kit: buttons, fields, modal windows, tables, and notifications received unified states and theme tokens.

The components were connected as reusable blocks — a page is assembled from ready-made elements rather than coded from scratch.

What it became

Assembling a typical page was reduced to a few hours — the components are already described and tested. The share of pages with layout discrepancies dropped from 60-70% to isolated cases, because the appearance is set by a single source.

New functionality is rolled out 3-4 times faster: a developer takes a ready-made block instead of repeating the markup. A change to the corporate style is now edited in one place and propagates automatically across all 40+ sections.

How is a custom component different from a standard one in Bitrix24?

A standard component is what already ships with the product and is updated together with the core. Its area of responsibility ends at standard scenarios: an entity card, a list with a filter, an edit form, a kanban.

As long as the task fits within that set, no custom work is needed: you get ready-made behavior, and platform updates reach you without your involvement.

As soon as non-standard logic appears — your own field order, composite permissions, calculated statuses, nested relationships between entities — the standard component starts to resist, and "tweaking" it through the template turns into a fragile construction.

A custom component is your own code that solves exactly your task and is not tied to the internal structure of the standard one. The key difference is not in the amount of code, but in who is responsible for its behavior when the core is updated.

The standard one is updated by the vendor, but breaks from your edits in the template. The custom one does not break from updates because it does not inherit the internals of the core — but you are the one who has to update and test it.

Hence the different support costs. A standard component is cheaper at the start and almost free to operate as long as you do not touch its template. A custom one is more expensive upfront, but predictable: its behavior does not depend on what has changed inside the platform.

The main cost item in both cases is not the writing, but the subsequent refinements, so what matters most is how cleanly the component is separated from the core.

Core compatibility is solved architecturally. A custom component should be built on the platform's public interfaces, not on direct calls to internal tables and service methods.

Then a core update does not turn into a revision of the entire interface: only those places change where you deliberately used an unstable interface. We record such points separately — that is what interface support is, not rewriting from scratch.

The practical selection criterion is simple: if the task is described by a standard scenario — we take the standard one and do not reinvent anything.

If the logic is unique and will evolve — we build a custom one, but with a clear boundary of responsibility and a plan for its maintenance. The mixed option, where a standard component is hung with edits in the template, is the most expensive to support, and we do not offer it.

Technical concerns before starting work

Before starting, almost every team asks the same questions: will we break the current portal, how do we migrate pages that are already live, and what will happen to responsiveness under load.

Below are engineering answers without marketing, so you can compare them against your own infrastructure.

How do we migrate existing pages without downtime?

We migrate page by page: the old template and the new component coexist, and we switch traffic via routing. First we migrate low-risk pages, verify form behavior and access rights, then the critical sections. Rollback means returning the route to the previous template, without rolling back data.

Will the portal handle the load after switching to React components?

Client-side rendering changes the load profile: part of the work moves to the browser, and the server delivers data instead of ready-made markup.

We measure time to interactive and the volume of transferred data on real scenarios, cache reference data, and split the bundle by route. On peak-load sections we test behavior under concurrent sessions so that degradation is predictable rather than sudden.

How is the UI tested if the visual part is hard to cover with automated tests?

We cover component logic with unit tests, and states and permissions with integration tests on the test portal. We catch visual regressions with snapshots of key screens, and we check accessibility by contrast and keyboard navigation. Every component goes into the portal only with a completed set of checks.

Let's discuss your portal UI layer task

To come back with an estimate and a plan rather than generalities, we need a minimum of inputs about your portal. We gather them in a single conversation — after that, engineers calculate the scope and risks, and you get a work plan with stages and acceptance points.

• Access to the portal and source code: repository, branch, development environment, read permissions for module and template settings.
• A list of screens and scenarios to be covered: cards, lists, forms, widgets, embeds into existing sections.
• Where the UI currently lives: stock templates, third-party solutions, custom components — what we reuse, what we rewrite.
• Behavior requirements: roles and permissions, required fields, loading and error states, mobile behavior.
• Design materials: mockups, UI kit, theme tokens, responsive rules — or we agree that we'll draw part of it ourselves.
• Environment constraints: core version, installed modules, update policy, load and access requirements.
• Acceptance criteria: which checks we consider passed and on which environment we demonstrate the result.

Based on these inputs, we break the work into stages: audit of the current UI layer, design of components and their relationships, implementation, integration into the portal, scenario verification, and handover.

At each stage, we record a result that can be viewed on the environment — this way the plan stays manageable instead of turning into "we'll do it and show it at the end."

Describe the task in free form: what kind of portal it is, which screens are hurting, and what result you need. We'll come back with a timeline estimate, scope of work, and a stage-by-stage plan.