UI Styles
Allows developers to define CSS class-based styles in YAML files that site builders can apply to blocks, layout builder components, regions, views, CKEditor content, and more.
ui_styles
Install
composer require 'drupal/ui_styles:8.x-1.19'
Overview
UI Styles is a comprehensive styling framework for Drupal that bridges the gap between theme developers and site builders. Developers define reusable styles (collections of CSS classes) in YAML files within modules or themes, while site builders can easily apply these styles through intuitive admin interfaces without writing code.
The module provides a plugin-based architecture where styles are defined declaratively with labels, descriptions, categories, and options. Each option maps to one or more CSS classes that get applied to the target element. The system intelligently detects whether to render form widgets as checkboxes (single option), select/radios (multiple options), or icon toolbars (when icons are provided).
A key feature is the automatic stylesheet generation that extracts only the relevant CSS rules from theme libraries, making the styles available for preview in admin interfaces and CKEditor. This ensures WYSIWYG-like behavior when selecting styles.
Features
- YAML-based style definition system allowing developers to declare reusable CSS class combinations with labels, descriptions, categories, and preview configurations
- Smart form widget rendering that automatically selects the appropriate widget type (checkbox for single options, radio buttons with preview for multiple options, icon toolbar when icons are provided)
- Automatic stylesheet generation that parses theme CSS libraries and extracts only the relevant CSS rules for defined style options
- Category-based organization of styles with collapsible groups in admin forms
- Theme-aware style filtering that only shows styles defined by the current theme and its base themes
- Extra classes field allowing site builders to add arbitrary CSS classes beyond predefined options
- Visual indicators showing which styles are currently applied to elements
- Support for style previews with configurable preview classes and display modes (inside, aside, hidden)
- Support for icons on style options enabling visual icon-based toolbars
- External documentation links support for style definitions
- Ability to disable inherited styles by declaring enabled: false with a higher weight module/theme
Use Cases
Bootstrap-based theme styling
A theme developer using Bootstrap defines UI Styles for common Bootstrap utility classes like background colors (bg-primary, bg-secondary), text colors, spacing utilities, and border styles. Site builders can then apply these Bootstrap classes to blocks, sections, and regions without knowing the CSS class names, simply by selecting 'Primary Background' or 'Large Padding' from dropdown menus.
Content editor visual styling in CKEditor
With the CKEditor 5 integration, content editors can apply predefined styles to text and paragraphs directly in the WYSIWYG editor. For example, they can select a paragraph and apply a 'Highlighted Box' style or select text and apply an 'Important' inline style, seeing the result immediately in the editor.
Layout Builder component styling
When using Layout Builder, site builders can style individual sections and blocks. Each section can have styles applied to the section wrapper and its regions, while each block can have separate styles for its wrapper, title, and content areas. This enables flexible visual layouts without custom templates.
Unpublished content visual indication
Using UI Styles Entity Status, a theme can automatically apply a semi-transparent overlay or distinctive border to unpublished content, making it visually obvious to editors which content is not yet live, without needing custom code.
Views styling without template overrides
Site builders can style Views output through the admin interface: apply a card-style layout to the exposed form, add a grid class to the format/style output, and style the pager with custom colors. All without touching template files.
Design system documentation
The Styles Library page serves as living documentation for the theme's design system. Developers define styles with descriptions and preview classes, and the library page becomes a reference showing all available styles with live examples that content editors and site builders can consult.
Tips
- Define styles in your theme's THEMENAME.ui_styles.yml file for theme-specific styling, or in a custom module for reusable styles across themes
- Use categories to organize related styles together - they appear as collapsible groups in the admin UI
- The 'previewed_with' property lets you add helper classes (like padding or borders) to make style previews more visible in the library
- Set 'previewed_as: aside' for styles that don't work well on paragraph text, like float or position utilities
- Use 'previewed_as: hidden' for styles with side effects that shouldn't be previewed in the library
- You can disable an inherited style by creating a definition with the same ID and 'enabled: false' in a higher-weight module or theme
- The 'extra classes' field in all style forms allows site builders to add custom CSS classes beyond the predefined options
- Styles are automatically filtered by theme - only styles from the active theme and its base themes are available
- For icon-based style selection, set the 'icon' property on either the style definition or individual options
- External documentation can be linked using the 'links' property to help editors understand when to use each style
Technical Details
Admin Pages 3
/admin/appearance/ui/styles
A comprehensive overview page displaying all available styles grouped by category. Each style shows its label, description, options with live CSS previews, and any external documentation links. Useful as a reference for site builders and content editors.
/admin/appearance/regions-styles
Overview page listing all installed themes with links to their individual region styles configuration pages.
/admin/appearance/regions-styles/{theme}
Configuration page for a specific theme where styles can be applied to each region defined in that theme. Each region gets a collapsible styles form with all available style options plus an extra classes field.
Permissions 1
Hooks 1
hook_ui_styles_styles_alter
Allows modules to alter style plugin definitions after they are collected from YAML files but before they are cached.
Troubleshooting 4
Verify the YAML file is correctly named (YOURMODULE.ui_styles.yml or YOURTHEME.ui_styles.yml) and properly formatted. Clear caches after adding or modifying style definitions. For theme-specific forms, ensure styles are defined by the current theme or its base themes.
The stylesheet generator needs access to CSS files. Ensure your theme's libraries are correctly defined and the CSS files are accessible. The /ui_styles/stylesheet endpoint generates the preview CSS - check it returns the expected styles.
Verify the style definition options map to valid CSS classes that exist in your theme. Check that the target element's template supports the #attributes or #item_attributes property where classes are being added.
Ensure the CKEditor 5 plugins are enabled in your text format configuration. The editor loads styles from /ui_styles/stylesheet?prefix=.ck-content - verify this endpoint returns your style CSS rules.
Security Notes 2
- The 'extra classes' field accepts arbitrary CSS class input from site builders. While this only adds classes (not arbitrary HTML), ensure users with access to style configuration are trusted as they can affect site appearance.
- Style definitions in YAML files should come from trusted sources as they define CSS classes that will be added to rendered output.