Layout Options

Provides a Layout plugin that allows configuration options to be easily added to layouts using YAML files and custom LayoutOption plugins.

layout_options
1,781 sites
50
drupal.org
api theme
layout layout builder styling css YAML Configuration theming layout options
Drupal 9 Drupal 10 Drupal 11

Install

Drupal 11, 10 v8.x-1.7
composer require 'drupal/layout_options:8.x-1.7'
Drupal 9 v8.x-1.5
composer require 'drupal/layout_options:8.x-1.5'

Overview

Layout Options is a powerful module that extends Drupal's Layout system by providing a flexible way to add styling and configuration options to layouts. Instead of writing PHP code, site builders can define layout options through YAML files, making it easy to add CSS classes, ID attributes, and other customizations to layouts and their regions.

The module works by providing a custom Layout plugin class (LayoutOptions) that replaces the default layout class. This plugin reads configuration from *.layout_options.yml files discovered in modules and themes, then generates appropriate form elements for configuring layouts in Layout Builder or Entity Reference Layouts. The configured values are then applied as HTML attributes during rendering.

The module supports theme inheritance, allowing base themes to define options that can be extended or overridden by sub-themes. Options can be applied globally to all layouts, to specific layouts by ID, or even to specific field contexts when used with Entity Reference Layouts.

Features

  • Define layout configuration options via YAML files without writing PHP code
  • Add ID attributes to layouts and layout regions using the layout_options_id plugin
  • Add CSS classes via text input using the layout_options_class_string plugin
  • Add CSS classes via select dropdowns using the layout_options_class_select plugin with single or multiple selection support
  • Add CSS classes via checkboxes using the layout_options_class_checkboxes plugin
  • Add CSS classes via radio buttons using the layout_options_class_radios plugin
  • Configure options to apply only to the main layout, only to regions, or both
  • Restrict options to specific regions using the allowed_regions setting
  • Apply options globally to all layouts or target specific layout IDs
  • Support for field-specific options when used with Entity Reference Layouts
  • Theme inheritance support allowing sub-themes to extend or override base theme options
  • Automatic CSS identifier validation to ensure valid class names and IDs
  • Weight-based sorting for controlling the order of form elements
  • Extensible plugin system for creating custom layout option types

Use Cases

Adding Bootstrap background colors to layouts

Create a YAML definition that allows content editors to select Bootstrap background color classes (bg-primary, bg-secondary, etc.) for layouts and regions. Define the options as a select dropdown and apply them globally so they appear on all layouts.

Theme-specific design classes

Define a set of CSS classes specific to your theme (e.g., layout--narrow, layout--wide, layout--centered) as checkboxes. Site builders can quickly apply these design variations without editing code.

Adding custom IDs for anchor links

Use the layout_options_id plugin to allow content editors to add custom HTML IDs to layouts and regions. This enables creating anchor links for in-page navigation.

Entity Reference Layouts field-specific options

When using Entity Reference Layouts module, define options that only appear for specific fields. For example, a hero_section field might have different styling options than a content_blocks field.

Layout-specific customizations

Define options that only apply to certain layouts. For example, a two-column layout might have options for controlling column ratios, while a single-column layout has different margin options.

Sub-theme option extensions

Create a base theme with core layout options, then extend these in a sub-theme to add client-specific styling options. The sub-theme can add new options or override existing ones.

Region-only spacing controls

Define padding and margin classes that only apply to regions, not the main layout wrapper. Use allowed_regions to further restrict certain options to specific regions like sidebars.

Tips

  • Create a custom module for your site's layout options rather than adding them to a theme - this ensures options remain available even if themes change
  • Use meaningful option IDs that describe their purpose (e.g., layout_bg_color, layout_spacing) for better maintainability
  • Set appropriate weights on options to group related settings together in the configuration form
  • Use the global section for commonly used options, and layout-specific sections only when needed
  • When creating custom LayoutOption plugins, extend the OptionBase class to leverage built-in validation and form building utilities
  • Test layout options with different themes to ensure CSS classes work as expected across different design systems
  • Use the allowed_regions setting to prevent irrelevant options from appearing in certain regions
  • The submodule Layout Options UI only shows layouts using the default LayoutDefault class - custom layout plugins won't appear in the override list

Technical Details

Admin Pages 1
Layout Options Override Settings /admin/config/system/layout_options/config

This page allows administrators to select which layouts should be overridden to use the Layout Options class instead of the default Layout class. This enables adding configuration options to layouts that weren't originally designed to support them.

Hooks 2
hook_layout_option_info_alter

Allows modules to alter the layout option plugin definitions after they are discovered. Can be used to modify existing option types or add/remove functionality.

hook_layout_alter

Used by Layout Options UI submodule to override layout classes. Can be used to programmatically set layouts to use the LayoutOptions class.

Troubleshooting 6
Layout options don't appear in the configuration form

Ensure your layout is using the LayoutOptions class. Either define a custom layout with class: '\Drupal\layout_options\Plugin\Layout\LayoutOptions' or enable Layout Options UI and select the layout to override. Also verify your YAML file is correctly named and placed in the module/theme root directory.

Changes to YAML file not reflected

Clear all Drupal caches (drush cr) after modifying *.layout_options.yml files. The YAML discovery caches file contents.

Theme options not overriding module options

Ensure your theme is set as the default theme. Only the default theme and its base themes are considered in the theme hierarchy. Other installed but non-active themes are filtered out.

Error messages about invalid plugin id

Verify the plugin ID in your YAML matches exactly with an available LayoutOption plugin (layout_options_id, layout_options_class_string, layout_options_class_select, layout_options_class_checkboxes, layout_options_class_radios). Plugin IDs are case-sensitive.

CSS classes not being applied to rendered output

Check that your layout template uses the attributes variable. Ensure the classes are valid CSS identifiers - the module validates and rejects invalid identifiers.

Form validation errors for CSS identifiers

CSS identifiers cannot start with numbers and can only contain letters, numbers, hyphens, and underscores. The module uses Html::cleanCssIdentifier for validation.

Security Notes 3
  • All user-entered values are sanitized using Html::escape() before being stored or rendered
  • CSS identifiers are validated using Html::cleanCssIdentifier() to prevent invalid or malicious class names
  • The Layout Options UI admin page requires 'administer site configuration' permission