ckeditor5_scroll_fix
CKEditor 5 Scroll Fix
Summary
This module fixes a common issue in Drupal 10+ with CKEditor 5 where the page scroll becomes locked or jumps unexpectedly after focusing on an image or widget in the editor. It intelligently detects page scrolling and simulates a click outside the editor to restore normal scrolling behavior, improving the editing experience for long content without any configuration required.
Full Description
Introduction
In Drupal 10 and later, CKEditor 5 is the default rich text editor, providing powerful features for content creation. However, a known limitation in its widget system (e.g., for images, media, or tables) can cause the page to scroll unexpectedly or lock when an element gains focus. This is particularly noticeable in long articles or pages where the editor is part of a larger form.
The CKEditor 5 Scroll Fix module addresses this by using a lightweight JavaScript behavior to monitor page scrolls. When a scroll is detected while the focus is inside the CKEditor 5 editable area (and the mouse is outside), it forces the focus back to the page body, simulating a natural "click away" action. This restores smooth scrolling without disrupting the editing workflow.
This module is inspired by community discussions on Drupal.org issues like #3410598: CKEditor 5: scroll jump after dialog close(https://www.drupal.org/project/drupal/issues/3410598) and #3401231: Simplenews 4.x(https://www.drupal.org/project/drupal/issues/3401231), providing a simple, drop-in solution for site builders and content editors.
Key Features
- Automatic Detection: Hooks into form alters to attach the fix only to forms using CKEditor 5 (e.g., node edit forms).
- Intelligent Focus Management: Uses DOM events to detect scrolls, blur the editor, and simulate mouse events for a seamless user experience.
- Zero Configuration: No admin settings needed—just enable the module, and it works on all relevant forms.
- Performance Optimized: Lightweight JS with debouncing to prevent excessive event handling; only loads on editor pages.
- Compatibility: Tested with Drupal 10.2+ and CKEditor 5; supports common themes like Claro and Olivero.
- Extensible: Easily extendable via hooks for custom forms (e.g., paragraphs or blocks).
Requirements
- Drupal core: ^10
- CKEditor 5 module (enabled and configured on at least one text format)
Installation
1. Download and extract the module to `modules/contrib/ckeditor5_scroll_fix`.
2. Enable the module: `drush en ckeditor5_scroll_fix -y`.
3. Clear caches: `drush cr`.
4. Test on a node edit form with CKEditor 5—insert an image, focus it, and scroll the page.
No further setup is required. The module automatically attaches its library to compatible forms.
Usage
Once enabled, the fix applies globally to all CKEditor 5 instances. For advanced users:
- Extend the form alter hook to target custom entities (e.g., in a custom module).
- Debug by inspecting browser console for event logs (if enabled in dev mode).
Recommended Modules
- Media Library: Enhances image insertion, where the scroll issue is most common.
- Paragraphs: If using nested editors, the module's recursive detection handles them seamlessly.
Similar Projects
- Core patches in Drupal issues (e.g., #3410598): Temporary fixes, but this module provides a stable, contrib solution.
- Other CKEditor tweaks like "CKEditor 5 Balloon Toolbar Fix": Focus on toolbar positioning, not scrolling.
Support and Contributions
- Report bugs or request features in the issue queue.
- Pull requests welcome on the Git repository.
- If this module helps you, consider sponsoring development or leaving a review!
This module is maintained actively and aims to be merged into core if the issue persists. For questions, check the Drupal.org forums or Stack Exchange.