Customizing Standard Component Templates in 1C-Bitrix
The layout is approved, the markup is ready, but catalog.element renders the product card not according to design — this is a typical integrator pain point. Direct editing of /bitrix/components/ guarantees loss of changes upon the first system update. The industrial approach is custom templates in /local/ that avoid touching the kernel. Over many years, we have overridden templates for more than 50 projects — from online stores with catalogs of 100,000 items to corporate portals. Not a single failure during updates. Certified 1C-Bitrix specialists ensure compatibility with current platform versions. In this article, we'll cover how to create a custom template correctly and avoid typical mistakes.
Why You Should Not Edit Templates in /bitrix/
Modifying files in /bitrix/components/bitrix/ leads to their replacement during update installation. Even if the update does not affect the template, changes will disappear with the next patch. The correct method is overriding via /local/. Bitrix looks for a component template in the following order:
-
/local/templates/<site_template>/components/<namespace>/<component>/<template>/ -
/local/components/<namespace>/<component>/templates/<template>/ -
/bitrix/templates/<site_template>/components/... -
/bitrix/components/<namespace>/<component>/templates/<template>/
It is enough to create the required folder structure in /local/ and place the overridden file there. The original in /bitrix/ remains untouched. Custom templates are 5 times more reliable than kernel editing — our experience confirms this. For in-depth study, I recommend the official documentation on component templates.
| Criteria | Editing in /bitrix/ | Custom template in /local/ |
|---|---|---|
| Preservation during updates | Lost | Fully preserved |
| Maintenance | Chaotic, hard to track | Versioning, clear structure |
| Conflict risk | High | Minimal |
| Setup time | Minutes (unreliable) | Hours (reliable) |
How to Safely Customize a Component Template
Let's take bitrix:catalog.element — the product card. We look at the original but do not touch it:
// Original template (do not touch) // /bitrix/components/bitrix/catalog.element/templates/.default/template.php // Our custom template in /local/ // /local/templates/my_site/components/bitrix/catalog.element/.default/template.php // /local/templates/my_site/components/bitrix/catalog.element/.default/style.css // /local/templates/my_site/components/bitrix/catalog.element/.default/script.js In template.php, all variables prepared by the component are available: $arResult, $arParams, $arCurrentValues. View their composition via \Bitrix\Main\Diag\Debug::dump($arResult) or the component bitrix:diag.phpinfo.
Include the template in the page code:
<?$APPLICATION->IncludeComponent( "bitrix:catalog.element", ".default", // template name [ "IBLOCK_TYPE" => "catalog", "IBLOCK_ID" => 12, ], false );?> If you need a separate template for a specific page or section, create a template with an arbitrary name, e.g., card_v2, and specify it during the call.
Customizing Templates of Complex Components
Complex components (bitrix:catalog, bitrix:news) consist of several included components. The complex component template contains component_epilog.php and subfolders for subcomponents:
/local/templates/my_site/components/bitrix/catalog/.default/ template.php component_epilog.php bitrix/ catalog.section/ .default/ template.php catalog.element/ .default/ template.php This allows you to override the layout of the section and the product card within a single catalog template.
What Are result_modifier.php and component_epilog.php?
Two files that provide access to component data without overriding its logic:
result_modifier.php — executes after the main component code, before the template. Here you can modify $arResult:
// result_modifier.php if (!empty($arResult['ITEMS'])) { foreach ($arResult['ITEMS'] as &$item) { $item['PRICE_FORMATTED'] = number_format($item['CATALOG_PRICE_1'], 0, '.', ' ') . ' ₽'; } } component_epilog.php — executes after the template. Used for final manipulations: setting page title, adding breadcrumbs, including scripts.
<?php // component_epilog.php $APPLICATION->SetTitle('Product Catalog'); $APPLICATION->AddChainItem('Home', '/'); $APPLICATION->AddChainItem('Catalog'); ?> Including CSS and JS in a Component Template
// In template.php $this->addCSS($this->GetFolder() . '/style.css'); $this->addJS($this->GetFolder() . '/script.js'); // Or via Asset Manager for file aggregation \Bitrix\Main\Page\Asset::getInstance()->addCss($this->GetFolder() . '/style.css'); What Is Included in Template Customization
- Template development — overriding all necessary templates according to your layout.
- Documentation — description of structure, changes, and maintenance instructions.
- Compatibility testing — verification with the current Bitrix version and updates.
- Staff training — how to make changes without risk.
- Post-implementation support — bug fixes and consultations for one month.
What Mistakes Are Most Often Made During Customization?
- Editing files in
/bitrix/— guaranteed loss of changes. - Creating a template without considering the nesting of a complex component — parts of the catalog do not work.
- Ignoring
result_modifier.php— code is duplicated in the template, complicating maintenance. - Using absolute paths to files — problems when moving to another hosting.
Timelines
| Task | Timeline |
|---|---|
| Custom template for one component (card, list) | 4–16 hours |
| Templates for all catalog components according to layout | 3–5 days |
| Customization of a complex component with sub‑templates | 2–4 days |
Contact us to discuss your project — we will assess complexity and timelines. Get a consultation if you want to avoid update issues and obtain a reliable solution.
Official 1C-Bitrix documentation on component templates
Our Approach to Solutions
Each task requires individual analysis and careful planning. We do not use template solutions — every project is adapted to specific requirements and existing infrastructure. Our team has experience with projects of various scales: from small stores to high‑load platforms with millions of operations per day.
Guarantees and Support
We provide a 12‑month warranty on completed work. During this period, we fix any issues free of charge. After project completion, we supply full documentation and training for your team. Technical support is available for 30 days after launch — we help resolve any questions.