Block Class
Allows assigning custom CSS classes, HTML attributes, and IDs to blocks through the user interface without modifying theme templates.
block_class
Install
composer require 'drupal/block_class:^4.0'
Overview
Block Class provides a comprehensive solution for adding custom CSS classes, HTML attributes, and IDs to any block through Drupal's standard block configuration interface. This eliminates the need for theme template modifications or technical knowledge to control the HTML output of blocks.
The module stores block styling configuration in Drupal's configuration system using third_party_settings, making it easy to export and deploy changes across environments. It integrates seamlessly with all Drupal core API modules and works with any theme that properly renders block attributes.
Version 4.x provides advanced features including multiple textfields for classes, autocomplete functionality, bulk operations for managing classes across all blocks, and comprehensive settings for controlling field behavior. The module supports uppercase/lowercase enforcement, special character handling, and custom CSS identifier filtering.
Features
- Add custom CSS classes to any block through the block configuration form
- Override or remove the HTML ID of blocks (use <none> to remove the ID entirely)
- Add custom HTML attributes to blocks in key|value format (e.g., data-block-type|info)
- Autocomplete functionality for previously used classes and attributes
- Multiple textfield mode allowing one class per field with add/remove buttons
- Bulk operations to insert, update, convert case, or delete classes and attributes across all blocks
- Block list view showing all configured classes and attributes with edit/delete links
- Class list and attribute list views showing all defined values
- Configurable maxlength for class, attribute, and ID fields
- Weight configuration to control field ordering on block forms
- Case enforcement (uppercase, lowercase, or standard)
- Special character filtering with customizable Html::cleanCssIdentifier settings
- Configuration exported with block settings for easy deployment
Use Cases
Adding CSS classes for layout styling
Add CSS classes like 'footer-left', 'sidebar-promo', or 'hero-section' to blocks to enable targeted CSS styling without modifying theme templates. Navigate to the block configuration, enter your classes in the CSS class field (one per line in multiple mode or space-separated in textfield mode), and save. The classes will be added to the block's wrapper div.
Adding data attributes for JavaScript functionality
Add custom data attributes to blocks for JavaScript interactions. Enable attributes in module settings, then when editing a block, add attributes like 'data-behavior|accordion' or 'data-tracking|header-cta' in the attribute fields. These will render as data-behavior="accordion" in the block's HTML.
Standardizing block IDs across environments
Use the ID replacement feature to set consistent block IDs regardless of the auto-generated Drupal block ID. Enter your custom ID in the ID field. Use '<none>' to completely remove the ID attribute from a block for accessibility or styling reasons.
Bulk updating class names during rebranding
When rebranding requires updating class names across all blocks, use the Bulk Operations page. Select 'Update class', enter the current class name and the new class name, and the operation will find and replace that class across all blocks.
Enforcing CSS class naming conventions
Configure the module to enforce lowercase-only class names for team consistency. In settings, set Default Case to 'Lowercase' and disable special characters. All classes will be automatically converted to lowercase when saved.
Exporting block styling with configuration
Since Block Class stores configuration in third_party_settings, all CSS classes, attributes, and custom IDs are exported with the block configuration. Use Drupal's configuration export/import to deploy block styling changes across environments.
Tips
- Use multiple textfields mode for cleaner class management - it prevents typos and makes it easier to remove individual classes
- The autocomplete feature remembers all previously used classes, making it faster to apply consistent styling across blocks
- When using '<none>' as the ID value, the block's ID attribute is completely removed from the HTML output
- Classes are automatically sanitized using Html::cleanCssIdentifier unless special characters are enabled
- Use the Advanced settings to configure character replacement rules if you have specific naming conventions
- The module integrates with all block types including Views blocks, Custom blocks, and contrib module blocks
- Export your configuration to version control to track changes to block styling over time
- Use bulk operations to quickly apply a common class to all blocks when implementing site-wide styling changes
Technical Details
Admin Pages 6
/admin/config/content/block-class/settings
Configure global settings for the Block Class module including field types, maxlengths, weights, and feature toggles for classes, attributes, and ID replacement.
/admin/config/content/block-class/list
View all blocks that have Block Class configuration (classes or attributes) with options to edit or delete the configuration.
/admin/config/content/block-class/bulk-operations
Perform bulk operations on classes and attributes across all blocks including insert, update, convert case, and delete operations.
/admin/block-class/help
Displays help information about Block Class module including usage instructions, configuration options, and links to administration pages.
/admin/config/content/block-class/class-list
View all CSS classes that have been used in block configurations. Useful for reference when adding classes to new blocks.
/admin/config/content/block-class/attribute-list
View all attributes that have been used in block configurations in inline format.
Permissions 1
Hooks 4
hook_block_presave
Processes block class configuration before saving, including case conversion and storing classes/attributes for autocomplete.
hook_form_block_form_alter
Adds CSS class, attribute, and ID fields to the block configuration form.
hook_preprocess_block
Adds configured CSS classes, attributes, and ID to the block's render array variables.
hook_help
Provides help text for the Block Class module help page.
Troubleshooting 7
Ensure your theme's block template properly renders the attributes variable. Check that {{ attributes }} or similar is present in block.html.twig. The classes are added to $variables['attributes']['class'] during preprocessing.
Verify that 'Enable autocomplete' is checked in the module settings. Classes are stored when blocks are saved, so you need to save at least one block with a class before it appears in autocomplete.
By default, special characters are disabled. Go to /admin/config/content/block-class/settings and check 'Enable special characters' to allow them. Note that valid CSS class names still have restrictions.
If your Default Case setting conflicts with the bulk operation (e.g., trying to convert to uppercase when lowercase is enforced), the operation will show an error. Change the Default Case setting first or set it to 'Uppercase and Lowercase' to allow both.
The number of class fields is controlled by 'Quantity of classes per block' in settings. Increase this value if you need more fields. The module will automatically expand beyond this limit if a block already has more classes.
Verify that 'Enable attributes' is checked in module settings at /admin/config/content/block-class/settings.
These are reserved. Use the dedicated Class field for CSS classes. For ID, use the ID replacement feature instead of attributes.
Security Notes 4
- The 'administer block classes' permission is marked as restricted and should only be granted to trusted roles
- HTML attribute values are sanitized using Html::escape() to prevent XSS attacks
- CSS identifiers are processed through Html::cleanCssIdentifier() unless special characters are explicitly enabled
- The module validates that 'id' and 'class' cannot be used as attribute keys to prevent conflicts