English | Українська
An extension for EspoCRM that adds four customization tools to Administration → Customizations: custom CSS, custom colors, Kanban card options and role-based navigation menus.
- Custom CSS: add your own CSS to every page of EspoCRM, in a code editor with syntax highlighting.
- Custom Colors: create colors beyond the six built-in styles and use them for Enum and Multi-Enum options, layout panels and Toggle Switch fields.
- Kanban Options: show field names next to values on Kanban cards, set up separately for each board.
- Assigned Menu: choose which navigation tabs non-admin users see, by role or team. Global Search follows each user's navigation, and direct links to hidden entities can be blocked.
- EspoCRM 9.0 or newer (tested on EspoCRM 10)
- PHP 8.3 or newer
- Download the latest extension package (
.zip) from the Releases page. - In EspoCRM, go to Administration → Extensions.
- Click Upload, choose the downloaded file and click Install.
- Go to Administration → Clear Cache.
- Reload the page in your browser.
The tools are in Administration → Customization → Customizations.
Install a newer package over the installed one. Your settings are kept.
Add CSS that loads on every page of EspoCRM, after the built-in styles, for all users.
- Code editor: EspoCRM's own Ace editor with CSS syntax highlighting, autocompletion of CSS properties, line numbers and a dark editor theme on dark EspoCRM themes.
- Save: with the Save button or Ctrl+S (⌘S on Mac). The new CSS applies right away, the Custom CSS page included.
- Limit: 100,000 characters.
- Public: the CSS is served without login, because the login page uses it too. Don't put anything private in it.
If a rule ever hides the Custom CSS page (for example body { display: none }), open the page with &safeMode=1 at the end of its address:
https://your-crm.example.com/#Admin/customizations/tool=customCss&safeMode=1
The editor opens with your custom CSS switched off and a notice, so you can fix the rule. The CSS applies again when you leave the page.
Create your own colors in addition to EspoCRM's built-in styles (Default, Success, Danger, Warning, Info, Primary).
Each color has:
| Setting | Description |
|---|---|
| Name | Shown in style menus. |
| Color | Used for text and label backgrounds. State labels and panel headers use a light tint of it. |
| Dark themes | Optional color for dark themes (Dark, Glass). Leave it empty and the color is lightened automatically. |
| Label text | Auto picks black text on light colors and white on dark ones; or force White or Black. |
Each row shows a live preview of the color as text, a label and a state label. You can reorder colors and add up to 200.
Every color gets a fixed key, such as cc-k3f9q2, when it's created. Fields and layouts store that key, so renaming or recoloring a color updates everything that uses it.
Enum and Multi-Enum options. In Entity Manager → an entity → Fields → an Enum or Multi-Enum field, the style menu next to each option lists your colors after the built-in styles, below a divider. The color then shows everywhere EspoCRM styles that option:
- text and labels in detail, list and Kanban views, both regular and state labels ("Display as Label", "Label Type")
- Kanban column headers
- Multi-Enum items in edit mode and highlighted items in dropdowns
- stream status notes
Layout panels. In Layout Manager → an entity → Detail (also Detail (Small), side panels and bottom panels), the panel Style list offers your colors after the built-in styles, below a divider. A colored panel gets a tinted header, a darker shade for the header text and buttons, and matching borders, like the built-in panel styles. Custom colors also work with "Conditions making panel styled".
Toggle Switch fields. With the "Toggle Switch for Boolean Fields" extension installed, the YES and NO color pickers of Boolean fields list your colors too. The switches and the Field Manager preview use them, dark themes included. Version 1.3.0 and later of that extension support custom colors themselves. For version 1.2.0, this extension adds the support. Without Toggle Switch, nothing changes.
Options, panels and switches that still use a deleted color show without it: Default for switches, uncolored otherwise. Style menus list it as "Removed color (cc-…)" so you can see it and choose another.
Show field names next to values on Kanban cards. Every entity with the Kanban view enabled has its own settings, so each board can look different.
| Setting | Description |
|---|---|
| Label position | Same line as the value (Amount: $1,000) or Above the value (a small name over the value). |
| Show labels for empty fields | When off, a field's name is hidden on cards where the field has no value. |
| Fields | The fields currently on the board's cards. Tick the ones that should show their names. |
Edit card layout opens the Layout Manager for the entity's Kanban layout, where you add or remove fields. Field names come from the field labels, in each user's language.
Control which navigation items non-admin users see, based on their roles and teams.
Each rule has:
- Roles: the rule applies to users who have one of these roles, assigned directly or inherited through a team.
- Teams: the rule also applies to members of these teams.
- Visible in navigation: the items these users see. The checklist mirrors your navigation bar, with its sections, groups and their items, and URL tabs. It also lists other entities that have tabs, for users with their own tab lists. A group checkbox selects or clears all of its items.
How rules combine:
- A user matched by several rules sees the items of all of them.
- Users not matched by any rule see the usual navigation.
- Administrators, portal users and API users are never affected.
- Home is always shown, and a group with no visible items is hidden.
- Changes apply when users reload EspoCRM.
When enabled (the default), non-admin users only search the entities in their navigation bar, after the rules are applied. The navigation suggestions in Global Search follow the same items and list each one once. The search runs on the server through EspoCRM's own search service, so results, paging and access checks stay EspoCRM's.
Direct links to hidden entities
What happens when a user matched by a rule opens a link to an entity hidden from their navigation, for example a link pasted by a colleague:
| Mode | Result |
|---|---|
| Block entity pages, records still open (default) | The entity's list, create and other entity pages show EspoCRM's "403 You don't have access to this area." page. Records opened from link fields still open. |
| Block all pages, records too | Records of hidden entities are blocked as well, including from link fields. |
| Allow | Hidden entities open from links as usual. |
The block works on the very first page too, such as a link opened in a new tab or right after logging in. Only entities that can be navigation tabs count as hidden. Pages such as Preferences, notifications and user profiles are never blocked.
Assigned Menu hides navigation; it doesn't change access rights. This is what lets a role read an entity through link fields while that entity stays out of the menu:
- Link fields still show the names of records from hidden entities.
- Autocomplete in link fields still offers them.
The blocking of direct links happens in the browser, and the data stays reachable through EspoCRM's API wherever a role allows reading it. To keep data from a user entirely, use the role's permissions.
The tools are listed in this order by default: Custom CSS, Custom Colors, Kanban Options, Assigned Menu. Each has an order number (10, 20, 30, 40; lowest first). To change it, create custom/Espo/Custom/Resources/metadata/app/customizations.json with only the numbers you want to change:
{
"tools": {
"assignedMenu": {
"order": 5
}
}
}Then clear the cache (Administration → Clear Cache) and reload. Files in custom/Espo/Custom aren't touched by extension updates.
Uninstall in Administration → Extensions. Your settings stay in EspoCRM's configuration, so reinstalling restores everything.
While the extension is uninstalled:
- options keep their color keys but show uncolored
- Kanban cards show values only
- custom CSS doesn't load
- the navigation is unrestricted
-
Views the extension replaces. It provides its own subclasses of these EspoCRM parts:
- the Administration controller (
clientDefs.Admin.controller), for the Layout Manager panel styles - the navigation bar (
clientDefs.App.navbarView) - the Global Search box
Another extension that replaces one of them would conflict; in that case the one installed last wins.
- the Administration controller (
-
Kanban. Boards whose Kanban view is replaced by another extension keep that view, so field names don't appear there. Portal Kanban boards show the standard cards.
-
Browsers. Colors use the CSS functions
color-mix()and:has(), supported by current versions of Chrome, Edge, Firefox and Safari.
The extension's module is Customizations: custom/Espo/Modules/Customizations on the server, and client/custom/modules/customizations in the browser.
Configuration parameters
| Parameter | Content |
|---|---|
customColorsList |
Custom colors: key, name, color, dark theme color, label text. |
customCss |
The custom CSS. |
kanbanLabelFields |
Per entity: the fields that show their names on Kanban cards. |
kanbanEntityOptions |
Per entity: label position and whether names of empty fields are shown. |
assignedMenuEnabled, assignedMenuGlobalSearch, assignedMenuDirectLinks, assignedMenuRuleList |
Assigned Menu settings and rules. |
API routes
| Route | Access | Purpose |
|---|---|---|
GET /api/v1/CustomColors/stylesheet |
Public | Generated CSS for custom colors. |
POST /api/v1/CustomColors/previewStylesheet |
Administrators | CSS for unsaved colors (live preview). |
GET /api/v1/Customizations/customCss |
Public | The custom CSS. |
GET /api/v1/GlobalSearch |
Users | Replaces the core route; runs EspoCRM's own Global Search with the user's narrowed entity list. |
Integration points. The extension uses these EspoCRM mechanisms, without changing core files:
- Metadata builders: switch the option style picker, the Kanban record views and the Toggle Switch views to the extension's subclasses, only when the original views are present.
app.client.cssListandscriptList: load the stylesheets and the direct-link guard.app.appParams: sends each user's navigation restriction to the browser.- Field validators: check every setting on the server before it's saved.
English and Ukrainian are included. To add a language, copy files/custom/Espo/Modules/Customizations/Resources/i18n/en_US to a folder with the EspoCRM language code (e.g. de_DE), translate the values (keep keys and placeholders like {user} unchanged) and clear the cache.