Prefixing Custom Attributes
The Bolt team has been weighing the pros and cons of prefixing our Web Component prop names to avoid conflicts with global attribute names, assistive technology, and browser-specific quirks.
We're in agreement that custom attributes added to a non-custom-element (e.g. div, p) should be prefixed with data-. However, there's disagreement when it comes to custom elements (Web Components).
Should we prefix attributes/props on our Web Components?
Mostly to avoid conflicts with plain HTML attributes and related browser default CSS.
Do not prefix or namespace our Web Component props because it is not required according to the spec and makes our API unnecessarily verbose. It would require a lot of rework, updating existing components, for marginal gains. Yes, having every prop prefixed with bolt or b would protect us from future breaking changes, but future breaking changes are unlikely considering single-word prop names are permitted on custom-elements by the current spec and widely used*.
That said, we should be on alert for any usage of custom props that may interfere with assistive technology. For now, we can only assume that web assistive technologies follow the same spec we do. If specific issues come to our attention, we are willing to make exceptions and avoid a problematic prop name. For now, simply avoid using global attributes as props.
We must also watch out for browser quirks. Chrome has a known issue with the attribute "align", where it will automatically align your text if used. At the moment, the list of browser-specific attribute quirks is short. Let's document any other issues we run into. If the list grows significantly, it may be worth considering prefixing our props. For now, it's better to avoid a few known attributes than to rename a large numbers of well-functioning prop names.
No prefixes for custom attributes in custom elements but must avoid using the same name as plain HTML attributes. Use data attributes for custom attributes in regular elements.
*Some examples of Web Components in the wild without prefixes:
- Basic A11y Checklist
- Get started with Bolt locally
- Bolt Specific Standards and Conventions
- How to save SVG graphics and SVG icons
- Upgrade to minor release
- Upgrade to 4.x
- Upgrade to 5.x
- Release Workflow
- VS Code Configuration
- Bolt Doc Writing Guide
- Prefixing Custom Attributes
- Standard Props for Passing Content in Twig
- Building Websites with Bolt in Drupal
- From Design Mockup to Code
- Override with Utility Classes