Why custom interfaces break when the platform is updated
Custom controls are almost always built on direct DOM manipulation: the developer finds the needed node by class or structure, attaches handlers, and swaps out the markup. As long as the platform doesn't change, this works.
But the core gets updated — class names change, nesting order changes, mount points change — and the selector that yesterday found the filter field today returns an empty list.
The form silently stops submitting, the card doesn't load related entities, the filter loses its selected values.
The cost of such a conflict during an update is higher than it seems.
The problem doesn't surface at the moment of the upgrade, but a week later in production, when users are already working with the forms: requests aren't created, some data isn't saved, and the logs are silent, because the handler simply never attached.
Diagnosis takes days, because formally "nothing broke": the platform was updated, but what broke was our code, which was clinging to its internal workings.
The root cause is that custom interfaces treat the platform as someone else's page, rather than as a set of public components.
Any access to internal selectors, manual assembly of markup on top of the standard layout, custom modals and dropdowns — all of this is an implicit contract with a core version that no one is obligated to honor.
Developing Bitrix24 UI components on the standard set of components flips this dependency: the interface is assembled from public elements with guaranteed support, rather than from guesses about the internal structure.
Updating the platform then only affects those places where we ourselves decided to deviate from the standard — and that deviation is visible and documented, rather than smeared across dozens of selectors. Let's break down how this is addressed in practice.
What a transition to a single set of interface components delivers
A single set of components removes the main cost item in frontend — rebuilding the same control for every new screen.
A button, a modal window, a table with filters, a dropdown — all of this stops being written from scratch and is plugged in as a reusable component with already defined behavior.
In practice, the share of reusable code in a typical interface grows from 20–30% to 70–80%, and a new screen is assembled from ready-made blocks rather than from a blank slate.
The speed of building interfaces changes by a factor: where it used to take several days for layout and state debugging, a day remains for composition and data binding.
The component already handles what is usually forgotten in hand-rolled controls — loading and error states, blocking during submission, behavior on an empty response, keyboard accessibility, and correct grid spacing. This is not "prettier," it is less code that needs to be maintained.
Along with hand-rolled controls, an entire class of failures goes away.
Diverging spacing between sections, a button that is blocked on submission on one screen but not on another, a field that loses its entered value when switching tabs — all of this is a consequence of each control being written separately and in its own way.
A single set defines one behavior for all screens, and divergence becomes not a "quirk" but an error that is visible immediately.
A unified interface style stops being a task that must be constantly chased. Changes to tokens — color, radii, typography — are applied to all components at once rather than spreading across dozens of files.
A new developer on the team plugs into ready-made rules instead of figuring out why two similar forms have different validation logic.
Separately, it is worth considering that the set lives together with the platform: component updates come from a shared branch, and interface support does not turn into maintaining your own library.
Let's discuss your task — we'll come back with an estimate and a plan for transitioning the interface to a single set.
Component Integration Approaches: Comparing the Options
Implementing UI components is rarely an "all at once" affair: the portal's interface has a life of its own, and no one is ready to break working scenarios for the sake of uniformity.
In practice, teams choose between three integration options — from local replacement of individual elements to a full migration of the interface to a single set.
The difference between them is not about "beauty" but about the scope of regression that will have to be covered by tests.
| Option | When it fits | Limitations |
|---|---|---|
| Point replacement of controls | You need to quickly eliminate discrepancies in forms, buttons, and input fields on specific pages | Old and new elements coexist — visual seams, duplicate styles, some scenarios remain on the previous components |
| Hybrid layer | Gradual migration section by section: new pages go straight onto the single set, old ones are connected via wrappers | Requires maintaining two sets in parallel, coupling grows, wrappers must be removed as migration progresses |
| Full interface migration | The single set becomes a mandatory standard for the entire team and new tasks | A one-time large scope of work, a full regression run, synchronization with platform updates |
Point replacement delivers results within days: controls are brought to a uniform look, behavioral discrepancies disappear, but the interface remains heterogeneous.
The hybrid layer is a compromise for portals that cannot be taken down: migration proceeds section by section, and each step is verified separately.
Full migration eliminates the problem entirely, but requires the team to agree on the rules: one set, one set of patterns, no local exceptions.
The choice of option determines not only the scope of work but also how the codebase lives on afterward. If the hybrid is left in place forever, maintenance becomes more expensive: every platform update has to be checked against two sets.
That is why we always fix an exit point in the plan — when the wrappers are removed and the interface remains on the single set.
Implementation stages: from interface audit to handover to the team
We start the work with an inventory: we collect all the buttons, fields, tables, modal windows, and notifications that already live in the interface, and record discrepancies — where the same control is coded in three different ways, where hover states and errors are not described at all.
The output is a component map with priorities: what is reused most often and will deliver an effect immediately, and what appears in a single place and does not go into the library.
Next, we design the library structure: we lay out components by levels, agree on property naming, design tokens, and composition rules. This is the stage where it is cheaper to make a mistake on paper than to later rewrite dozens of screens.
- Interface audit. Inventory of controls, search for duplicates and discrepancies, reuse map and priorities.
- Library design. Component levels, unified properties, design tokens, nesting rules.
- Implementation. Assembly of components with a full set of states: default, hover, focus, loading, error, empty value.
- Scenario testing. Running through real screens — forms, lists, filters, bulk actions, access rights.
- Documentation. For each component — usage examples, allowed combinations, limitations.
- Handover to the team. Walkthrough with developers and designers, library update rules, the procedure for adding new components.
- Post-launch support. Reviewing feedback, versioning changes so that edits do not break already assembled screens.
The key moment is scenario testing: a component that looks beautiful in isolation often falls apart in a live form with validation, permissions, and long lists.
That is why we run through entire user paths rather than individual elements, and only after that do we lock in the library version.
Handover to the team is not a final presentation but a working process: developers get access to source files and documentation, designers get the extension rules. After that, the library lives on its own, and we get involved for contentious changes.
What remains in the project after the work is completed
A project built on Bitrix24 UI Kit lives longer than a sprint: a new developer inherits someone else's code, and without fixed rules components start to be duplicated and diverge in styles.
That is why we close out work not with a demonstration of the interface, but with the handover of a package that the client's team uses to continue developing Bitrix24 UI components on their own.
- Component library — assembled and typed interface elements with a unified property structure: buttons, fields, tables, modal windows, notifications. Each component is covered by loading, error, and empty-data states, not just the "happy" scenario.
- Usage rules — when to take a ready-made component, when to extend it through a wrapper, and why directly editing the source is prohibited. This is what keeps the library from sprawling into a dozen local copies.
- Component documentation — a description of properties, events, and constraints next to the code, with usage examples. A developer does not need to read the implementation to understand how to embed an element into their page.
- Integration examples — working sample pages where components are connected to data, forms, and access rights. They are the fastest way to reproduce the needed scenario in a new section.
- Support and update regulations — the procedure for adding components, versioning rules, branches, and the criteria under which a change is considered backward compatible.
- Build and publication scheme — the configuration by which the library is built and connected to the project, so that an update does not break already working sections.
- Decision log — recorded trade-offs: why this set of properties was chosen, which options were rejected, and what to do in case of a conflict with a platform update.
Such a package removes the main risk — the project's dependence on a specific contractor. The client's team sees not only the result, but also the logic by which it was assembled, and can develop the interface without us.
If you need to estimate the scope of handover for your project — describe the task, and we will come back with a plan and a list of artifacts.
Case study: how the portal interface stopped breaking after updates
What it was like before
The customer's portal is an internal system for several thousand employees: requests, approvals, reference data, reports. The interface was built on direct edits to templates and one-off scripts on top of the core.
Every platform upgrade turned into a lottery: after an update, filters in lists broke, validation in forms failed, and modal windows "drifted".
According to our ticket statistics, after another update 6-8 screens out of 40 broke — and those were only the ones users noticed. It took from three days to investigate and fix, and the fixes were made in the same templates that would break again on the next update.
What we changed
We moved the interface onto our own UI component layer on top of Bitrix24 UI Kit — a React library that the vendor maintains alongside the platform.
Forms, tables, filters, and modal windows became reusable components with a single contract: markup and logic live in one place, and pages are assembled from ready-made blocks.
Core updates no longer affect our components — their API does not depend on the portal's internal templates.
What it became
The share of broken screens during an upgrade dropped from 6-8 to zero: across several update cycles, not a single component required a fix. Recovery time after an update shrank from three days to a few hours — and even that was for checking, not fixing.
Shipping a new form sped up from two weeks to two or three days: a developer assembles it from ready-made fields and validation instead of writing markup from scratch.
Users no longer have to wait "until it's fixed after the update" — the interface behaves the same before and after an upgrade.
How Bitrix24 UI component development differs from template editing
Template editing changes what the user sees on a specific page: the markup, the order of blocks, the labels, the styles.
A component defines how that interface is assembled and how it behaves when data changes — which states it can display, how it reacts to a loading error, what happens with an empty response.
A template describes the result once, a component sets the rules by which the result is reproduced on all pages where it is connected.
The difference shows up on the second or third revision. While there are few edits, a template is cheaper and faster: you fix the markup — the task is closed.
But as soon as the same block is needed on five more pages, every edit has to be repeated, and discrepancies between the copies accumulate. A component pays off at this point: a change in one place propagates to all connections, and the behavior stays the same.
Bitrix24 UI component development is about state, not about appearance. A component describes what to show during loading, what a partially arrived response looks like, where the error message is output, and how the block behaves on a narrow screen.
A template does not distinguish such scenarios: it receives already prepared data and renders it the same way, so a loading failure looks like an empty area with no explanation.
When a template is enough: a one-off page, unique markup, data arrives in full and does not change, reuse is not planned. Here a component would add an extra layer with no benefit.
When a component is needed: the block repeats, it has several states, it receives data from an external source, or it must work the same way in different sections.
The sign is simple — if on the next edit you open the same template file again, it means the logic is due to be extracted.
Practical conclusion: a template and a component do not compete, they solve tasks at different levels. Template editing closes the symptom on one page, a component removes the cause — duplication of logic and divergence of behavior between pages.
Technical doubts before starting work
Before the start, the same set of questions usually comes up: how the new components will coexist with the current core, whether they will break the interface in employees' browsers, and whether the portal's responsiveness will degrade. Below are answers to the point, without generalities.
Will the components work on our current version of the product?
Yes, if the core is on a currently supported branch. We verify the version before starting and record it in the work plan: the component library evolves together with the platform, and on an outdated core some elements simply won't build.
If the version is behind, we first plan an upgrade — this is a separate stage with verification of extensions and customizations, so that the upgrade doesn't bring surprises along with it.
What about employees' old browsers?
The components are built for modern browsers, so for outdated versions we add polyfills and manually check key scenarios.
If the company has a fixed fleet of old machines, we run the interface on them in advance and either resolve the incompatibility or agree on a transition to a supported browser — but we don't leave it to chance.
Won't the portal become slower?
The build uses route-based code splitting: only what's needed on the current screen goes to the browser, not the entire set of components at once. Heavy blocks are loaded on demand, and state is cached.
In practice, this puts a comparable or lower load on the page than custom-built solutions — but we always measure on your data, not on a demo.
Can we roll back if something goes wrong?
Yes. Work proceeds in separate branches, the release is staged, and each stage can be removed without losing what's already been done. Before rollout we record a return point, so an unsuccessful release rolls back to a working state rather than turning into emergency recovery.
If you still have questions about your environment — access, extensions, or integrations — describe the task, and we'll come back with an estimate and a plan.
Let's discuss your task and come back with a work plan
To come back with a work plan rather than generalities, we need input on your task. The more specific the input, the more accurate the estimate of timelines and scope of work — and the fewer clarifications needed already at the project kickoff stage.
What helps us quickly put together a proposal:
- A list of screens and scenarios where components are needed: cards, tables, forms, filters, modal windows — with a note on which are already in the standard set and which will have to be built.
- A link to the current interface or mockups: even rough sketches remove half the questions about the composition and behavior of elements.
- Requirements for states: loading, empty result, error, access rights — they determine the scope of work no less than the screens themselves.
- Data and integrations: which entities we pull, from where, whether work with REST and external services is needed.
- Timeline constraints and priorities: what is critical for launch, what can be moved to the second stage.
- Access to the repository and the test environment — if the project is already underway, this speeds up the start by several days.
In response, you will receive a breakdown by stages with an estimate of labor costs, a list of components with priorities, a scheme for their reuse, and a work plan with checkpoints.
We will separately note the risks: where coordination with the current markup will be required, and where discrepancies with expectations regarding behavior are possible.
Describe the task in any convenient form — a list, a link to mockups, or a short message. We will study the input and come back with an estimate and a work plan.