Block Styles

Allows altering Drupal blocks using template suggestions and custom CSS classes through the block configuration form.

block_styles
1,576 sites
39
drupal.org
gui theme
blocks theming templates styles bootstrap layout appearance
Drupal 8 Drupal 9 Drupal 10 Drupal 11

Install

Drupal 11, 10, 9, 8 v2.0.5
composer require 'drupal/block_styles:^2.0'

Overview

Block Styles provides a flexible way to change the appearance of blocks by applying alternative templates and CSS classes without writing code. The module integrates with the Styles API to allow selection of pre-defined style templates directly from the block configuration form.

When editing a block in the Block Layout interface, administrators can select from available style templates that replace the default block.html.twig template. Additionally, custom CSS classes can be added to the block wrapper, and for interactive styles (like modals or dropdowns), custom button text can be specified.

The module works by creating a config entity that stores style settings for each block, then uses hook_theme_suggestions_block_alter() to add the selected template suggestion and hook_preprocess_block() to add CSS classes and button text variables to the template.

Features

  • Select alternative block templates from a dropdown in the block configuration form
  • Add custom CSS classes to block wrappers via a simple text field
  • Configure custom button text for interactive style templates (modals, dropdowns, collapses)
  • Provides a 'Clean Wrapper' template that strips away default block wrapper markup
  • Integrates with the Styles API plugin system for extensible style definitions
  • Supports theme-specific styles that only apply when the provider theme is active
  • Stores style configuration as exportable config entities

Use Cases

Display a block as a Bootstrap modal dialog

Enable block_styles_bootstrap, edit a block, select 'Bootstrap Modal' from the style dropdown, and enter custom button text. The block content will be hidden and displayed in a modal when the button is clicked. Useful for login forms, contact forms, or supplementary content that shouldn't take up page space.

Create collapsible sidebar blocks

Apply the 'Bootstrap Collapse' style to sidebar blocks to make them collapsible. Users click a button to expand/collapse the block content. Ideal for mobile-friendly sidebars or reducing visual clutter while keeping content accessible.

Style blocks as Bootstrap cards

Use the 'Bootstrap Card' style to wrap block content in a Bootstrap card component with proper header and body sections. The block title appears in the card header and content in the card body.

Remove default block wrapper markup

Apply the 'Clean Wrapper' style to remove the default Drupal block wrapper HTML, useful when integrating with CSS frameworks or when the default block markup conflicts with your theme's design.

Add custom CSS classes to blocks

Without changing templates, add custom CSS classes to any block's wrapper element through the block configuration form. Useful for applying utility classes, custom styling, or framework-specific classes.

Create dropdown menus from blocks

Apply 'Bootstrap Dropdown' style to navigation or content blocks to display them as dropdown menus triggered by a button click. The dropdown stays open when clicking inside it, allowing for interactive content.

Tips

  • Use the 'Clean Wrapper' style when you need full control over block markup without the default Drupal wrapper elements
  • For Bootstrap styles to work properly, your theme must already include the Bootstrap framework
  • Custom CSS classes added through Block Styles are applied to the outermost block wrapper element
  • The button text field defaults to the block's configured label if left empty
  • Style settings are stored as config entities and can be exported/imported with Drupal's Configuration Management
  • New styles can be added by modules or themes through the Styles API plugin system without modifying Block Styles

Technical Details

Hooks 3
hook_theme_suggestions_block_alter

Adds the selected style template as a theme suggestion for blocks

hook_preprocess_block

Adds CSS classes and button text variables to block templates

hook_form_block_form_alter

Adds the Block Styles fieldset to block configuration forms

Troubleshooting 4
Bootstrap styles don't work or look broken

Ensure your theme includes Bootstrap CSS and JavaScript libraries. The block_styles_bootstrap submodule only provides templates that use Bootstrap markup - it does not include the Bootstrap framework itself.

Style options don't appear on block edit form

Make sure the Styles API module is installed and enabled. Block Styles requires Styles API to discover available style plugins.

Theme-provided styles only work sometimes

Theme-specific styles only apply when that theme is active. If a style is provided by a specific theme, it won't appear or function when using a different theme.

Button text field is disabled or hidden

The button text field only appears for styles that have 'extras.label' enabled in their definition. Not all styles support custom button text.