{"id":13804618,"url":"https://github.com/ember-a11y/ember-a11y-refocus","last_synced_at":"2026-04-27T06:01:17.942Z","repository":{"id":37829396,"uuid":"184625166","full_name":"ember-a11y/ember-a11y-refocus","owner":"ember-a11y","description":"Accessible routing for Ember apps.","archived":false,"fork":false,"pushed_at":"2026-02-19T19:10:55.000Z","size":1026,"stargazers_count":19,"open_issues_count":7,"forks_count":11,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-02-19T22:55:12.749Z","etag":null,"topics":["a11y","accessibility","ember","ember-addon","hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ember-a11y.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-05-02T17:44:31.000Z","updated_at":"2026-02-19T19:10:23.000Z","dependencies_parsed_at":"2023-11-24T19:31:14.845Z","dependency_job_id":"851304b8-3c7d-4a5c-bc1f-0ee1dced5c20","html_url":"https://github.com/ember-a11y/ember-a11y-refocus","commit_stats":{"total_commits":148,"total_committers":16,"mean_commits":9.25,"dds":0.7094594594594594,"last_synced_commit":"a23d94b3587135a16d6ec76f1e7bacecf2454756"},"previous_names":["melsumner/ember-a11y-refocus"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/ember-a11y/ember-a11y-refocus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-a11y%2Fember-a11y-refocus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-a11y%2Fember-a11y-refocus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-a11y%2Fember-a11y-refocus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-a11y%2Fember-a11y-refocus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ember-a11y","download_url":"https://codeload.github.com/ember-a11y/ember-a11y-refocus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-a11y%2Fember-a11y-refocus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32324552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a11y","accessibility","ember","ember-addon","hacktoberfest"],"created_at":"2024-08-04T01:00:51.267Z","updated_at":"2026-04-27T06:01:17.913Z","avatar_url":"https://github.com/ember-a11y.png","language":"TypeScript","funding_links":[],"categories":["Packages"],"sub_categories":["a11y"],"readme":"# ember-a11y-refocus\n\n[![Latest NPM release](https://img.shields.io/npm/v/ember-a11y-refocus.svg)](https://www.npmjs.com/package/ember-a11y-refocus)\n[![Ember Observer Score](https://emberobserver.com/badges/ember-a11y-refocus.svg)](http://emberobserver.com/addons/ember-a11y-refocus)\n[![Publish Stable](https://github.com/ember-a11y/ember-a11y-refocus/actions/workflows/publish.yml/badge.svg)](https://github.com/ember-a11y/ember-a11y-refocus/actions/workflows/publish.yml)\n\n## What This Addon Does\n\nIn order to provide a mechanism for Ember applications to meet certain WCAG Success Criteria, this addon does three things:\n\n1. Transition message: it adds a message to the page to let the screen reader user know that the route has changed.\n2. Transition focus management: it moves the focus to that message for the screen reader user, effectively resetting focus in Ember apps (similar to how a native web page/site works).\n3. Skip link: It provides a bypass mechanism so the user can skip to the page's primary content (see \u003chttps://www.w3.org/TR/WCAG20-TECHS/G1.html\u003e).\n\nThere are quite a few options, and many things are customizable.\nMake sure to read the whole README file to fully understand how to use this addon!\n\n## Why This Addon is Needed\n\nSingle-Page Applications(SPAs) use `pushState` to allow portions of the page to be updated or replaced without a whole new page being rendered. While this was a positive gain for performance on the web, it has made an entire type of web app not accessible (usable) for folks who depend on assistive technology(such as screen-readers) to use the web. With the prolific rise of JavaScript frameworks as the tool of choice for building modern web applications, screen-reader users have become increasingly left out of many experiences of the modern web that have become necessary for everyday life, such as online banking, paying bills, and ordering products and services.\n\nSince `pushState` does nothing to inform the browser--and, by extent, the screen reader--that new content is present, the screen-reader user has no way of knowing that new content exists, or that navigation to a new page was successful. Additionally, focus remains where it was, instead of being reset in a predictable fashion.\n\n## Installation\n\n```bash\npnpm add ember-a11y-refocus\n```\n\nOr with npm:\n\n```bash\nnpm install ember-a11y-refocus\n```\n\n## Usage\n\n- Insert `\u003cNavigationNarrator/\u003e` into your application.hbs file, inside of the `\u003cheader\u003e` element.\n- Next, add `id=\"main\"` to the primary content element in your application (should be the `\u003cmain\u003e` element).\n\nExample:\n\n```html\n\u003cheader\u003e\n  \u003cNavigationNarrator/\u003e\n  \u003c!-- other header content--\u003e\n\u003c/header\u003e\n\u003cmain id=\"main\"\u003e\n \u003c!--main content--\u003e\n\u003c/main\u003e\n```\n\nGjs/Gts:\n\n- Import the `NavigationNarrator` \n- Insert `\u003cNavigationNarrator/\u003e` component into your template file, inside of the `\u003cheader\u003e` element.\n- Next, add `id=\"main\"` to the primary content element in your application (should be the `\u003cmain\u003e` element).\n\nExample:\n\n```gjs\nimport { NavigationNarrator } from 'ember-a11y-refocus';\n\n\u003ctemplate\u003e\n  \u003cheader\u003e\n    \u003cNavigationNarrator/\u003e\n    \u003c!-- other header content--\u003e\n  \u003c/header\u003e\n  \u003cmain id=\"main\"\u003e\n   \u003c!--main content--\u003e\n  \u003c/main\u003e\n\u003c/template\u003e\n```\n\nTemplate Registry is available for loose mode users:\n\n```ts\nimport type EmberA11yRefocusRegistry from 'ember-a11y-refocus/template-registry';\n\ndeclare module '@glint/environment-ember-loose/registry' {\n  export default interface Registry\n    extends EmberA11yRefocusRegistry {}\n}\n```\n\nMinimal CSS is provided to style the skip link and navigation message.\n\n```diff\n/* app/app.ts */\n+ import 'ember-a11y-refocus/styles/navigation-narrator.css';\n+\nimport Application from '@ember/application';\nimport loadInitializers from 'ember-load-initializers';\nimport Resolver from 'ember-resolver';\n\nimport config from './config/environment';\n\nexport default class App extends Application {\n  modulePrefix = config.modulePrefix;\n  podModulePrefix = config.podModulePrefix;\n  Resolver = Resolver;\n}\n\nloadInitializers(App, config.modulePrefix);\n```\n\n\u003cdetails\u003e\n\n\u003csummary\u003eUse Sass?\u003c/summary\u003e\n\nIf your build tool resolves node module paths (e.g. Vite), the full specifier works directly:\n\n```scss\n/* app/styles/app.scss */\n@use \"ember-a11y-refocus/styles/navigation-narrator.css\";\n```\n\nFor classic Ember apps using `ember-cli-sass`, add the path to `includePaths`:\n\n```js\n// ember-cli-build.js\nconst app = new EmberApp(defaults, {\n  sassOptions: {\n    includePaths: ['node_modules/ember-a11y-refocus/dist/styles'],\n  },\n});\n```\n\nThen import with the short path:\n\n```scss\n/* app/styles/app.scss */\n@use \"navigation-narrator.css\";\n```\n\n\u003c/details\u003e\n\n### Feature: Customizing the definition of a route change\n\nThis addon provides support for custom definitions of which route changes should trigger refocusing behavior.\nTo use this functionality, pass `routeChangeValidator` when you invoke the component, and add your custom action in the appropriate controller (likely the application controller).\n\nSo when you add the component to your application template:\n\n```hbs\n\u003cNavigationNarrator @routeChangeValidator={{this.myCustomValidator}} /\u003e\n```\n\nThis is what the controller could look like:\n\n```js\nimport Controller from '@ember/controller';\n\nexport default class ApplicationController extends Controller {\n  myCustomValidator(transition) {\n    // Custom logic goes here...\n  }\n}\n```\n\nThe validator function:\n\n- Receives a [Transition](https://api.emberjs.com/ember/release/classes/Transition) object containing information about the source and destination routes\n- Should return `true` if refocusing should occur, otherwise `false`\n\n**Note:** If you wish to extend the default behavior (rather than completely replacing it), you can import the default validator like so:\n\n```js\n import Controller from '@ember/controller';\n import { defaultValidator } from 'ember-a11y-refocus';\n\n export default class ApplicationController extends Controller {\n   myCustomValidator(transition) {\n     if (transition.from.name === 'special') { // this if statement is where you'd put your custom route validation\n        return false;\n     } else { // include this to get the defaultValidator as a fallback\n        return defaultValidator(transition);\n     }\n   }\n }\n ```\n\n## Additional Options\n\nAll of these are optional and have default values.\n\n- `skipLink` - pass `{{false}}` if you do not want to implement a bypass block/skip link.\n- `skipTo` - pass a specific element ID that should receive focus on skip. Defaults to `#main`.\n- `skipText` - customize the text passed in the skip link. Defaults to `Skip to main content`.\n- `navigationText` - customize the text passed as the navigation message. Defaults to `The page navigation is complete. You may now navigate the page content as you wish`.\n- `excludeAllQueryParams` - pass `{{true}}` if you want to exclude all query params from the route change check/focus management. Really shouldn't do this, but you might be upgrading an older app and need this for a little bit, or you are using QPs in a specific way and would like to otherwise benefit from the accessibility options in this addon. If you only need to exclude _some_ QPs, use the [custom validator function](https://github.com/ember-a11y/ember-a11y-refocus?tab=readme-ov-file#customizing-the-definition-of-a-route-change) instead.\n\n## FastBoot\n\nWith FastBoot, you'll want to guard the `\u003cNavigationNarrator /\u003e` from rendering. Like so:\n\n```hbs\n{{#unless this.fastboot.isFastBoot}}\n  \u003cNavigationNarrator /\u003e\n{{/unless}}\n```\n\nWhere `this.fastboot` is the fastboot service injected in the application controller.\n\n## FAQs\n\n### What about async data loading?\n\nAsync data can be loaded as it normally would be. Since this addon does not use `aria-live`, it won't interfere with or compete with other loading states. This will only give the user with a screen reader a message that the route (URL) has changed, and place the focus where they expect it to be (reset to the top left of the page).\n\n### What if I want to put focus somewhere specific in the app flow?\n\nSince this will run before other content, focus can be programmatically moved by the developer to go somewhere else. The message should still read out, and is findable by users with screen readers.\n\n## Compatibility\n\n- Ember.js v4.12 or above\n- Node.js v22 or above\n\n## Contributing\n\nContributions are welcome.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fember-a11y%2Fember-a11y-refocus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fember-a11y%2Fember-a11y-refocus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fember-a11y%2Fember-a11y-refocus/lists"}