CKEditor Accordion
Adds an accordion widget to CKEditor 5, enabling content editors to create and display collapsible content sections using a clean definition list markup structure.
ckeditor_accordion
Install
composer require 'drupal/ckeditor_accordion:^2.3'
Overview
CKEditor Accordion integrates a powerful accordion component into Drupal's CKEditor 5 text editor. This module allows content editors to create expandable/collapsible content sections directly within the WYSIWYG editor, making it easy to organize lengthy content into digestible, interactive sections without requiring any technical knowledge.
The accordion widget uses semantic HTML definition list markup (<dl>, <dt>, <dd>) for the underlying structure, ensuring accessibility and proper content structure. In the editor, users see a visual representation with clearly labeled title and content areas, while the frontend displays a fully interactive accordion with smooth animations.
The module provides a configurable settings page where administrators can control default accordion behavior such as whether tabs start collapsed, whether multiple tabs can be open simultaneously, animation effects, and support for anchor links to specific accordion sections via URL hashes.
Features
- Adds an Accordion button to the CKEditor 5 toolbar for inserting accordion widgets
- Contextual balloon toolbar appears when editing accordion content with options to add rows above/below or delete rows
- Uses semantic HTML definition list markup (dl, dt, dd) ensuring proper document structure and accessibility
- Smooth animated open/close transitions with configurable animation settings
- Support for URL hash-based deep linking to specific accordion tabs (e.g., #FrequentlyAskedQuestions)
- Configurable default state: collapsed or first tab open
- Option to keep multiple accordion rows open simultaneously or close others when opening one
- Minimal blue styling that is easily overridable by theme developers
- Triggers 'ckeditorAccordionAttached' JavaScript event when accordions are initialized for integration with other frameworks
- Full keyboard navigation support with accordion tabs rendered as accessible links
- Automated CKEditor 4 to CKEditor 5 upgrade path for seamless migration
- Frontend library automatically attached to all pages containing accordion content
Use Cases
Creating FAQ Sections
Use the accordion widget to create Frequently Asked Questions sections where each question is a collapsible accordion title and the answer is the expandable content. Enable 'Open tabs with hash' to allow direct linking to specific questions (e.g., yoursite.com/faq#HowDoIResetMyPassword).
Product Feature Descriptions
Organize product information into collapsible sections for features, specifications, compatibility, and support information. Users can expand only the sections they're interested in without scrolling through lengthy content.
Step-by-Step Tutorials
Create multi-step tutorials or guides where each step is an accordion row. Users can expand individual steps as they progress through the tutorial, keeping the page organized and focused.
Terms and Conditions / Legal Content
Present lengthy legal documents, terms of service, or privacy policies in accordion format, organizing content by topic. This improves readability and allows users to quickly navigate to specific sections.
Multi-Topic Documentation Pages
Create documentation or help pages covering multiple topics. Each accordion row can address a different topic, allowing users to quickly find and expand only the information they need.
Tips
- The accordion uses definition list HTML markup (dl, dt, dd) which provides semantic meaning - consider this when planning your content structure
- Override the default blue styling by targeting the .ckeditor-accordion-container CSS classes in your theme
- Enable 'Keep accordion rows open' when users might want to compare content between multiple sections
- Use meaningful accordion titles that work as hash anchors when 'Open tabs with hash' is enabled, as special characters are stripped (e.g., 'Frequently Asked Questions' becomes #FrequentlyAskedQuestions)
- The contextual toolbar appears when your cursor is inside an accordion - use it to quickly add or remove rows without returning to the main toolbar
- Nested accordions are not supported by design - the module explicitly prevents placing accordions inside accordion content areas
- Animation duration is fixed at 300ms with an ease-in-out timing function; customize by overriding the JavaScript or CSS if needed
Technical Details
Admin Pages 1
/admin/config/content/ckeditor-accordion
Configure the default behavior of accordions created using the CKEditor Accordion widget. These settings affect how accordions are displayed and behave on the frontend of the website.
Permissions 1
Hooks 1
hook_page_attachments_alter
Used by the module to attach the accordion.frontend library and pass accordion configuration settings to drupalSettings on every page load.
Troubleshooting 6
Ensure you have added the Accordion button to the active toolbar in the text format configuration at /admin/config/content/formats. Edit the desired text format and drag the Accordion button from available items to the active toolbar.
Check that the accordion.frontend library is being loaded. Clear Drupal caches and verify no JavaScript errors in browser console. The library should automatically attach via hook_page_attachments_alter.
Enable 'Open tabs with hash using anchor links or on page load' in the module settings at /admin/config/content/ckeditor-accordion. Note that accordion titles are converted to hash anchors by removing spaces and special characters.
If animations appear choppy, try disabling animations in module settings. Performance issues may occur on pages with many accordions or on slower devices.
The module provides minimal default styling. Override the .ckeditor-accordion-container and related CSS selectors in your theme. Add !important if needed to override the module's styles.
The module includes an automated upgrade path. Run database updates after upgrading to ensure the update hook runs. If issues persist, re-save the text format configuration.
Security Notes 3
- The 'administer ckeditor accordion' permission is marked as restricted access and should only be granted to trusted administrator roles
- The module does not sanitize accordion content - rely on Drupal's text format filtering for XSS protection
- URL hash parameters are URL-encoded to prevent injection attacks when 'Open tabs with hash' is enabled