In design systems, composite input components—such as tag pickers, autocomplete dropdowns, and token selectors—often handle internal keyboard events to navigate suggestion lists. However, when a component aggressively stops event propagation (event.stopPropagation()), it can inadvertently break surrounding containers like modal dialogs, drawers, and overlay popups.
In my recent contribution to GitLab's Pajamas Design System (MR !6678, closing Work Item #3762), I resolved a keyboard accessibility barrier in @gitlab/ui's GlTokenSelector that prevented modal dialogs from closing on Escape.
Here is an architectural look at the problem, how WAI-ARIA recommends handling nested keyboard contexts, and how we solved it in Vue.
1. The Bug: Trapped Inside the Modal
GlTokenSelector is the multi-selection token input used across GitLab to assign labels, users, milestones, and security tags.
Inside GlTokenSelector, the text input had an inline event modifier attached to catch keypresses:
<!-- Before in GlTokenSelector.vue -->
<input
ref="input"
@keydown.stop="$emit('keydown', $event)"
...
/>
The .stop modifier in Vue unconditionally invokes event.stopPropagation().
The Real-World Breakdown
When GlTokenSelector is embedded inside a modal dialog (GlModal), users expect standard keyboard navigation:
- Focus Input: The user types to search for tokens. A dropdown opens with suggestions.
- Press Escape (1st time): The suggestions dropdown should dismiss, returning focus to the input.
-
Press Escape (2nd time): Because the dropdown is closed, the
Escapekey should bubble up toGlModaland close the dialog!
Because @keydown.stop caught and swallowed every Escape keydown event, the event never reached the modal container. Users had to manually reach for their mouse to close the modal—violating WCAG 2.1.1 (Keyboard Accessible) and frustrating power users.
2. The Solution: Conditional Event Propagation
According to the W3C WAI-ARIA Dialog Pattern, when an active input inside a modal does not have its own popup or combobox menu open, pressing Escape must close the dialog.
To resolve this, we removed the blind @keydown.stop modifier and implemented programmatic event propagation:
<!-- After in GlTokenSelector.vue -->
<input
ref="input"
@keydown="handleKeydown"
...
/>
In the component's script:
handleKeydown(event) {
if (event.key === 'Escape') {
this.handleEscape(event);
return;
}
// Non-Escape keys remain contained inside the token selector
event.stopPropagation();
this.$emit('keydown', event);
},
handleEscape(event) {
if (this.dropdownIsOpen) {
// 1st Escape: Close dropdown and prevent bubbling to parent modal
event?.stopPropagation?.();
this.closeDropdown();
} else {
// 2nd Escape: Dropdown already closed, let Escape bubble up to GlModal!
this.$emit('keydown', event);
}
}
How It Works:
-
When Suggestions are Open:
event.stopPropagation()fires, cleanly closing the dropdown without triggering the parent modal. -
When Suggestions are Closed: Propagation is not stopped. The event bubbles up the DOM tree, allowing
GlModal's root key listener to catchEscapeand close the dialog as expected.
3. Unit Testing Keyboard Propagation
To safeguard against regressions, we added unit test suites in token_selector.spec.js using Jest/Vue Test Utils to verify propagation states:
describe('when Escape key is pressed', () => {
it('stops propagation when suggestions dropdown is open', () => {
createComponent({ dropdownIsOpen: true });
const stopPropagation = jest.fn();
findInput().trigger('keydown', {
key: 'Escape',
stopPropagation,
});
expect(stopPropagation).toHaveBeenCalled();
});
it('allows propagation to bubble to parent when dropdown is closed', () => {
createComponent({ dropdownIsOpen: false });
const stopPropagation = jest.fn();
findInput().trigger('keydown', {
key: 'Escape',
stopPropagation,
});
expect(stopPropagation).not.toHaveBeenCalled();
});
});
Key Takeaways for Design System Engineers
-
Be Cautious with
.stopModifiers: Avoid applying@keydown.stopor@click.stopindiscriminately on inputs. Child components frequently live inside composite parents (modals, drawers, dropdowns) that rely on event bubbling. -
Follow Layered Escape Ergonomics: An
Escapepress should peel back one UI layer at a time: active tooltip $\rightarrow$ autocomplete menu $\rightarrow$ modal dialog. - Accessibility is Built in the Small Details: Fixing keyboard traps and ensuring predictable focus behavior makes design systems truly accessible to everyone.
Check out the merged Merge Request on GitLab:
👉 GitLab Design System MR !6678
Author: Manish Kumar
GitLab: @manishpatel00

Top comments (0)