A lightweight command system for handling DOM interactions through custom events and the `commandfor` attribute.
npm install @aegisjsproject/commands@aegisjsproject/commandsA lightweight command system for handling DOM interactions through command events and the commandfor attribute.
!Node CI
!Lint Code Base
!node-current
!npm bundle size gzipped
!GitHub forks
!GitHub stars
- - -
- Code of Conduct
- Contributing
This library is based on the Invoker Commands API.
Elements with a commandfor attribute automatically dispatch command events to their target elements when triggered. The
library handles these events with built-in commands or custom registered handlers.
``html`This content will be removed.
- --aegis-command-hide/--aegis-command-unhide - Controls hidden attribute--aegis-command-disable
- /--aegis-command-enable - Controls disabled attribute--aegis-command-remove
- - Removes element from DOM--aegis-command-scroll-into-view
- - Scrolls element into view (respects prefers-reduced-motion)--aegis-command-request-fullscreen
- /--aegis-command-exit-fullscreen/--aegis-command-toggle-fullscreen - Fullscreen API--aegis-command-show-picker
- - Opens input picker (date, color, etc.)--aegis-command-step-up
- /--aegis-command-step-down - Steps numeric inputs--aegis-command-open-details
- /--aegis-command-close-details/--aegis-command-toggle-details - Controls --aegis-command-play-media elements
- /--aegis-command-pause-media - Media element controls--aegis-command-request-picture-in-picture
- - Picture-in-picture for videos--aegis-command-copy-text
- - Copies element's textContent to clipboard
`js`
import { observeCommands } from './commands.js';
observeCommands(); // Observes document.body by default
).`js
import { registerCommand } from './commands.js';registerCommand('--my-command', (event) => {
console.log('Custom command triggered on', event.target);
});
`$3
Generates a unique command string and registers the callback.js
import { createCommand } from './commands.js';const cmd = createCommand((event) => {
event.target.style.color = 'red';
});
// Use
cmd as the command attribute value
`$3
Convenience function that returns a complete attribute string.js
import { command } from './commands.js';element.innerHTML =
;
`$3
Manually add command listener to specific elements.js
import { listenForCommands } from './commands.js';
listenForCommands(myElement, { once: true });
`Usage Patterns
$3
js
import { observeCommands } from './commands.js';
observeCommands();
`$3
js
import { observeCommands, registerCommand } from './commands.js';registerCommand('--toggle-class', (event) => {
event.target.classList.toggle('active');
});
observeCommands();
`$3
js
import { observeCommands, createCommand } from './commands.js';const toggleColor = createCommand((event) => {
const colors = ['red', 'blue', 'green'];
const current = colors.indexOf(event.target.style.color);
event.target.style.color = colors[(current + 1) % colors.length];
});
document.body.innerHTML +=
;
observeCommands();
`CommandEvent Properties
Command events extend regular events with:
-
- The element that triggered the command (the button/trigger)
- command - The command string that was executed#Memory Considerations
> [!WARNING]
> Command listeners are not automatically removed when elements are deleted. If you're frequently adding/removing elements with
commandfor attributes in long-running applications, consider using listenForCommands() with { once: true } for one-time interactions, or manually manage listeners for dynamic content.Security
Command registration closes automatically after initial setup. Call
closeCommandRegistration()` explicitly if needed for additional security.