Collapsiblock
Makes individual blocks collapsible by clicking on their titles, with smooth animations and optional state persistence via cookies.
collapsiblock
Install
composer require 'drupal/collapsiblock:^4.4'
Overview
Collapsiblock is a user interface enhancement module that allows any Drupal block to become collapsible. When enabled, users can click on a block's title to expand or collapse its content with a smooth sliding animation.
The module is designed for site-builders who are new to Drupal with relatively simple needs. It provides both global default settings and per-block configuration options, allowing fine-grained control over which blocks are collapsible and how they behave.
Key capabilities include cookie-based state persistence (so blocks remember their collapsed/expanded state across page loads), intelligent handling of menu blocks with active links, dark mode theme support, and full Layout Builder integration. The module also includes accessibility features such as ARIA attributes for screen readers and RTL (right-to-left) language support.
Features
- Make any block collapsible by clicking on its title, with smooth sliding animation
- Five collapse behavior options: None, Collapsible expanded by default, Collapsible collapsed by default, Always collapsed, and Always expanded
- Cookie-based state persistence to remember user preferences across page loads and sessions
- Intelligent active link detection that keeps menu blocks expanded when they contain active links
- Per-block configuration to override global defaults for individual blocks
- Full Layout Builder integration for managing collapsible blocks in Layout Builder contexts
- Dark mode support with configurable CSS class detection for theme color switching
- RTL (right-to-left) language support with appropriate arrow direction
- Configurable animation speed with nine preset options from 50ms to 1300ms
- GDPR-compliant option to disable cookies entirely
- Force-open class support allowing block content to prevent collapsing when needed
- Accessibility support with aria-expanded attributes for screen readers
Use Cases
Collapsible Sidebar Navigation
Make sidebar menu blocks collapsible so users can hide navigation they don't need, creating more space for main content. The active link detection ensures the current section stays visible.
FAQ Page with Collapsible Answers
Create blocks for each FAQ category and set them to collapsed by default. Users can expand only the sections they're interested in, making long FAQ pages more manageable.
Dashboard with Customizable Widgets
On a dashboard page with multiple information blocks, users can collapse widgets they don't need to see frequently while keeping important ones expanded. Cookie persistence remembers their preferences.
Mobile-Friendly Content Organization
On mobile devices where screen space is limited, collapsible blocks help organize content. Users can collapse sections to focus on what's important and expand them when needed.
E-commerce Product Filters
Make filter blocks in product listing sidebars collapsible. Users can hide filter categories they don't need, focusing on relevant filters while keeping the interface clean.
GDPR-Compliant Implementation
For sites that need to minimize cookie usage, set the cookie lifetime to -1 to disable state persistence entirely. Blocks will still be collapsible but won't store any user data.
Tips
- Use 'Collapsible, collapsed by default' (option 3) for sidebar blocks on content-heavy pages to reduce visual clutter while still making content accessible.
- The 'Always collapsed' and 'Always expanded' options (4 and 5) ignore cookies, making them ideal for blocks that should always start in a specific state regardless of user preferences.
- Animation speed of 200ms (the default) provides a good balance between visual feedback and responsiveness. Increase for a more noticeable effect or decrease for snappier interaction.
- When using with menu blocks, the active link detection works with links that have the 'is-active' class, which Drupal adds automatically to menu links pointing to the current page.
- For AJAX-updated content that should force a block to stay open, add the 'collapsiblock-force-open' class dynamically to the updated content.
- The module works with both the Block Layout system and Layout Builder, so you can use it regardless of how you manage your site's block placement.
Technical Details
Admin Pages 1
/admin/config/user-interface/collapsiblock
Configure global settings that apply to all collapsible blocks on the site. These settings serve as defaults that can be overridden on individual blocks.
Permissions 2
Hooks 6
hook_block_view_alter
Alters block render arrays to add Collapsiblock wrapper elements for standard block rendering (non-Layout Builder).
hook_form_block_form_alter
Adds the Collapsiblock settings fieldset to the block configuration form, allowing per-block collapse behavior settings.
hook_form_alter
Adds Collapsiblock settings to Layout Builder's 'Add Block' and 'Update Block' forms.
hook_page_attachments_alter
Attaches the Collapsiblock library and passes global settings to JavaScript on every page.
hook_preprocess_block
Processes block templates to inject Collapsiblock wrapper elements into title_prefix and title_suffix variables.
hook_help
Provides help text for the module on the Help page.
Troubleshooting 5
Ensure your theme's block template uses the {{ title_prefix }} and {{ title_suffix }} variables to wrap the block title. The JavaScript looks for these wrapper elements. Check that the block has a visible title (label_display is enabled) and the collapse behavior is not set to 'None'.
Check the Cookie lifetime setting. If set to -1, cookies are disabled. If blank, cookies expire when the browser closes. Set a positive number for persistent cookies. Also ensure the collapse behavior is set to option 2 or 3 (not 4 or 5, which ignore cookies).
This is intentional behavior to help users see their current location. To allow collapsing even with active links, check the 'Allow menu blocks to be collapsed on page load if they have active links' option in global settings.
Enable the 'Enable collapse arrow color switcher' option and specify the CSS class your theme uses to indicate dark mode in the 'Color mode trigger class' field. This class should be present on the html or body element when dark mode is active.
Add the CSS class 'collapsiblock-force-open' to the block's content or container. The JavaScript will detect this class and prevent the block from collapsing. Useful for blocks containing forms that need to remain visible.