Skip to main content
This guide covers how to customize OroCommerce and OroPlatform applications through themes, JavaScript architecture, and UI tooling. All customizations are organized around two distinct theme types and a shared JavaScript foundation.
Back-office themes cannot be used in the storefront and vice versa. The two systems have separate architectures and are not interchangeable.

​
Theme Types

Storefront Themes

Themes for the OroCommerce customer-facing storefront. Built on the OroLayouts framework with full layout update support.

Back-Office Themes

Themes for the Oro application back-office. A single-page application using Twig and Underscore.js templates with placeholder-based extensibility.

​
Additional Topics

JavaScript Architecture

Client-side architecture built on Chaplin and Backbone.js. Shared by both storefront and back-office with different JS module registration.

Storefront Style Guide

Create and customize OroCommerce storefront themes using Figma design files and the atomic design system.

​
Right-to-Left UI Support

Oro supports right-to-left (RTL) user interface development. To enable RTL:
1

Enable RTL for a localization

Select the Enable RTL Mode checkbox under System > Localization > Localizations.
2

Mark the theme as RTL-ready

Set the rtl_support: true option in the theme’s theme.yml configuration file. This triggers generation of an additional *.rtl.css output file during the build.
3

Review custom markup and scripts

Check whether custom markup, styles, and JavaScript require additional adjustments for RTL rendering.

​
Markup

For storefront layout development, use the is_rtl_mode_enabled context value: 
- '@setOption':
    id: root
    optionName: dir
    optionValue: '=context["is_rtl_mode_enabled"] ? "rtl" : ""'
For back-office Twig templates, use the oro_is_rtl_mode() function: 
<html {{ oro_is_rtl_mode() ? 'dir="rtl"' : ''}}>

​
Left-aligned values in RTL

Certain values — ZIP codes, phone numbers, PO numbers, SKUs, email addresses — should remain left-aligned regardless of text direction. Wrap them in a <bdo> tag: 
<bdo dir="ltr">1-(800)-555-5555</bdo>

​
JavaScript

Use the _.isRTL() mixing from underscore when functionality needs to change at the JavaScript level: 
import _ from 'underscore';

el.style[`margin-${_.isRTL() ? 'left' : 'right'}`] = `${offset}px`;

​
Auto-RTL style inputs

By default, all styles from Oro bundles are automatically processed by the RTLCSS post-processor. Extend the allowlist to include custom styles: 
# src/Acme/Bundle/DemoBundle/Resources/config/oro/assets.yml
auto_rtl_inputs:
    - 'bundles/oro*/**'

​
Build command

Use the standard build command. Add --skip-rtl to skip RTL style generation during development: 
php bin/console oro:assets:build --skip-rtl

Build docs developers (and LLMs) love

Get started for freeTalk to us