Style Options
A configurable style management API that enables attaching CSS classes, background colors, and background images to layouts, paragraphs, and other Drupal components through an extensible plugin system.
style_options
Install
composer require 'drupal/style_options:^1.1'
Overview
The Style Options module provides a comprehensive API for managing reusable style options throughout the Drupal ecosystem. It enables site builders and developers to attach configurable styles—such as CSS classes, background colors, and background images—to various Drupal components without writing custom code.
The module uses a YAML-based configuration system that allows defining style options in modules or themes. These options can then be applied to different contexts including Layout API layouts and Paragraph types. The extensible plugin architecture enables developers to create custom style option plugins for specialized styling needs.
Style Options includes built-in integration with the Layout API and Paragraphs module, providing a seamless editing experience. Editors can configure styles through intuitive forms with features like color pickers and file uploads. The module generates dynamic CSS that is automatically attached to rendered components.
Features
- CSS Class Plugin: Attach custom CSS classes to components with support for predefined options (select/radios) or freeform text input, with optional multiple selection capability
- Background Color Plugin: Add background colors using an integrated color picker (Spectrum.js) with configurable palette, alpha transparency support, and choice of CSS generation method (embedded style tags or inline styles)
- Background Image Plugin: Upload and apply background images with managed file handling, configurable upload location, file size limits, dimension validation, and automatic cover-style CSS generation
- Property Plugin: A generic plugin for attaching arbitrary property values to components, useful for custom implementations
- Layout API Integration: Built-in layout plugin class (StyleOptionLayoutPlugin) that enables style options for entire layouts and individual regions with a tabbed interface
- Paragraphs Behavior Integration: ParagraphsBehavior plugin that adds style options to paragraph type editing forms with per-bundle configuration
- YAML-Based Configuration: Define style options in [module].style_options.yml or [theme].style_options.yml files with support for defaults, overrides, and selective disabling
- Context-Aware Configuration: Configure which options appear for specific layouts, paragraph bundles, or other contexts with inheritance from defaults
- Extensible Plugin System: Create custom style option plugins by extending StyleOptionPluginBase and implementing StyleOptionPluginInterface
- Dynamic CSS Generation: Styles are rendered as embedded <style> tags in the page head with unique class names for conflict-free styling
- AJAX Support: Full support for AJAX-rendered content with styles properly attached as suffixes when in AJAX context
- Migration Tools: Built-in migration utility for transitioning from the Option Plugin module with automatic data conversion
Use Cases
Adding Custom CSS Classes to Layouts
Site builders can define a set of predefined CSS classes (e.g., 'container-wide', 'container-narrow', 'highlighted-section') in their theme's style_options.yml file. Editors can then select these classes when configuring layouts, applying consistent styling without needing to understand CSS.
Configurable Background Colors for Content Sections
Define a brand-approved color palette in the configuration. Content editors can apply background colors to paragraph types like 'Call to Action' or 'Featured Content' using the color picker, maintaining brand consistency while allowing creative flexibility.
Hero Sections with Background Images
Enable the background_image option for hero paragraph types. Editors can upload background images that are automatically styled with cover properties, creating visually impactful page sections without developer intervention.
Different Styling Options per Component Type
Using the context system, provide different style options for different components. For example, offer width classes for layout sections, background colors for paragraphs, and highlight styles for specific paragraph bundles.
Theme-Specific Brand Styling
Define all style options in your custom theme's style_options.yml. This keeps brand-specific styling configurations with the theme and allows easy updates when rebranding by modifying a single configuration file.
Extending with Custom Plugins
Developers can create custom style option plugins for specialized needs, such as gradient backgrounds, box shadows, or animation triggers. The extensible plugin system allows any style property to be made configurable.
Tips
- Use the '_defaults' key in contexts to set baseline options for all layouts or paragraph types, then override or disable specific options for individual components
- The '_disable' key in context definitions allows you to selectively remove options inherited from defaults without redefining everything
- Store your style_options.yml in your custom theme rather than a module to keep brand-specific styling configurations together with your theme assets
- When creating predefined options for the css_class plugin, include a 'None' option with an empty class value to allow users to remove styling
- Use the 'description' setting on options to provide editors with guidance on when and how to use each styling option
- For background colors, configure a palette that matches your brand colors to ensure consistency across the site
- When extending the module with custom plugins, implement the StyleOptionStyleTrait for consistent CSS generation behavior
- The 'method' setting on background_color and background_image plugins defaults to 'css' which generates style tags; use 'inline' only when style tags cause issues
Technical Details
Admin Pages 1
/admin/config/style-options/migrate
Migration utility for transitioning data from the Option Plugin module. This page provides a simple one-click migration process that converts paragraph behavior settings from the option_plugin format to the style_options format.
Hooks 2
hook_style_options_alter
Allows modules to alter the style option plugin definitions. Called by the plugin manager when plugin definitions are being collected.
hook_theme
Implemented by the module to register theme hooks for background_color and background_image style templates.
Troubleshooting 6
Ensure your layout definition uses StyleOptionLayoutPlugin as the class or extends it. Check that your style_options.yml file is properly formatted and placed in your module/theme root directory. Verify the layout context is configured in the 'contexts.layout' section.
Enable the 'Style Options' behavior for the paragraph type in the paragraph type configuration. Verify the paragraph bundle is configured in 'contexts.paragraphs' section of your style_options.yml file.
Install the Spectrum.js library at /libraries/spectrum/spectrum.js and /libraries/spectrum/spectrum.css. Clear Drupal caches after installation.
Ensure the upload directory exists and is writable. Check file system permissions. Verify the file scheme (public/private) is correctly configured in your option definition.
Clear all caches after configuration changes. Verify that the option values are being saved by checking paragraph/layout behavior settings. Check that the build method is correctly adding styles to the render array.
Ensure paragraph types have both option_plugin and style_options behaviors available. The migration only processes paragraphs where option_plugin behavior was enabled. Check for errors in the Drupal log.
Security Notes 4
- File uploads through the background_image plugin are validated for file extensions (gif, png, jpg, jpeg only), file size, and image dimensions
- Uploaded files are marked as permanent to prevent automatic cleanup, but are properly managed through Drupal's file system
- CSS values are rendered through Twig templates which provide auto-escaping, but custom plugins should ensure proper sanitization of user input
- The migration form requires 'administer site configuration' permission to prevent unauthorized data modifications