ember-a11y-landmarks
v2.0.0
Published
An ember addon for easier creation of correct landmark regions for better accessibility.
Downloads
22
Readme
ember-a11y-landmarks
The ember-a11y-landmarks addon helps you assign the role attribute that should go on landmark tags like <header> and <nav>, without needing to learn the intricacies of when to add roles or what they should be. A landmark is a special kind of semantic HTML tag that Assistive technology(AT) uses to parse a page correctly.
When is this addon needed? In a typical Ember app, almost everything gets wrapped in a <div>, but this can be confusing to tools like screen readers. The Assistive Technology expects that either landmark elements are direct descendants of the <body> element or that they have a particular role attribute. ember-a11y-landmarks handles this problem for you.
How this addon works
This addon helps add the correct roles to the following elements:
| tagName | role | | ------- | ------------- | | header | banner | | nav | navigation | | aside | complementary | | main | main | | form | form | | footer | contentinfo |
While semantic landmark tags are best for accessibility, some developers may be faced with working on an app that uses div tags instead. For those cases, this addon provides a way to add roles to a div element until they can be refactored (see Div Usage).
ember install ember-a11y-landmarksLandmark Tag Usage
This addon is used like a block component. Just set the tagName attribute to header, nav, aside, main, form, or footer, and put your content inside the block. For example, here's a header:
<A11yLandmark @tagName="header">
This is my header content
</A11yLandmark>The resulting markup in the DOM will have the correct tag type and the role that should be used for that tag:
<header id="ember337" role="banner" class="ember-view">
This is my header content
</header>Div Usage
If a developer must use a div instead of a semantic tag like <header>, define landmarkRole instead of tagname. You can look up the correct landmark role in the How this addon works table. Here's a header example:
<A11yLandmark @landmarkRole="banner">
This is my header content (that should be refactored later to go inside a real header tag)
</A11yLandmark>In the DOM markup, this will result in a div with the specified role:
<div id="ember337" role="banner" class="ember-view">
This is my header content (that should be refactored later to go inside a real header tag)
</div>Form/Search Usage
If defining a form, no additional landmarkRole is required. However, if the form will be used as a search, then the landmarkRole value should be set to search.
Form:
<A11yLandmark @tagName="form">
...
</A11yLandmark>Search:
<A11yLandmark @tagName="form" @landmarkRole="search">
...
</A11yLandmark>Contributions
Contributions to this project are encouraged.
Compatibility
- Ember.js v3.12 or above
- Ember CLI v2.13 or above
- Node.js v10 or above