{"id":25184084,"url":"https://github.com/thebeyondgroup/deep-focus-trap","last_synced_at":"2025-05-07T13:35:26.495Z","repository":{"id":47479247,"uuid":"487591418","full_name":"TheBeyondGroup/deep-focus-trap","owner":"TheBeyondGroup","description":null,"archived":false,"fork":false,"pushed_at":"2024-06-19T05:37:28.000Z","size":446,"stargazers_count":5,"open_issues_count":6,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-28T06:49:33.268Z","etag":null,"topics":["javascript","light-dom-elements","lit-element","shadow-dom"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/deep-focus-trap","language":"JavaScript","has_issues":false,"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/TheBeyondGroup.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/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}},"created_at":"2022-05-01T16:51:46.000Z","updated_at":"2025-02-10T05:16:13.000Z","dependencies_parsed_at":"2024-04-08T23:31:37.101Z","dependency_job_id":"a318e960-9097-4cf0-8709-61c4342483b4","html_url":"https://github.com/TheBeyondGroup/deep-focus-trap","commit_stats":{"total_commits":78,"total_committers":3,"mean_commits":26.0,"dds":"0.038461538461538436","last_synced_commit":"634ac5ac4e8f4bc7e782cc1f3cc1eeacc23f185d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheBeyondGroup%2Fdeep-focus-trap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheBeyondGroup%2Fdeep-focus-trap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheBeyondGroup%2Fdeep-focus-trap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheBeyondGroup%2Fdeep-focus-trap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheBeyondGroup","download_url":"https://codeload.github.com/TheBeyondGroup/deep-focus-trap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252887825,"owners_count":21819935,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["javascript","light-dom-elements","lit-element","shadow-dom"],"created_at":"2025-02-09T19:29:40.190Z","updated_at":"2025-05-07T13:35:26.462Z","avatar_url":"https://github.com/TheBeyondGroup.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Deep Focus Trap\n\n### Getting Started\n1. Install library using\n\n    ``` bash\n    $ npm install deep-focus-trap\n    ```\n2. Import library \n\n    ``` javascript\n    import { focusTrap } from 'deep-focus-trap';\n    ```\n3. Initalize class with config options:\n\n    ``` javascript\n     const focusTrap = new focusTrap({\n       el: '.modal'\n     });\n    ```\n4. Activate the focus trap when you need to trap focus with the element (i.e. when a user opens a modal).\n\n    ``` javascript\n    focusTrap.activate();\n    ``` \n5. Then deactivate when you no longer need to trap focus (i.e. when a user closes the modal).\n\n    ``` javascript\n    focusTrap.deactivate();\n    ``` \n#### Example\n``` javascript\nimport { focusTrap } from 'deep-focus-trap/dom'\n\nconst query = (selector) =\u003e document.querySelector(selector);\nconst modal = query('.modal')\nconst openModalBtn = query('.open-modal-btn');\nconst closeModalBtn = query('.close-modal-btn');\nconst focusTrap = new focusTrap({\n  el: '.modal',\n  escCallback: function (){\n    modal.style.display = 'none';\n  }\n});\n\n//open modal event\nopenModalBtn.onclick = function(){\n   modal.style.display = 'block';\n   focusTrap.activate();\n};\n\n//close modal event\ncloseModalBtn.onclick = function(){\n   modal.style.display = 'none';\n   focusTrap.deactivate();\n};\n```\n\n#### Piercing the Shadow DOM\n\nThe main import has two classes for import ` deepFocusTrap` and its parent `focusTrap`. If you don't need to pierce the shadow DOM you should import the parent class from the dom module  (i.e. `import { focusTrap } from 'deep-focus-trap/dom'`). This reduces the module size significantly as you won't import the dependency required to pierce the shadow DOM. The class that pierces the shadow DOM is `deepfocusTrap`. You can use this class by importing it from the main module like so: `import { deepFocusTrap } from 'deep-focus-trap'`. \n\nBoth `focusTrap` and `deepFocusTrap` have the same functionality and work in the same way except `deepFocusTrap` is able to pierce the shadow DOM. The reasons there are two classes broken into different modules is to enable tree-shaking, which greatly reduces the imported bundle size (**850B** compared to **12.5KB** minified \u0026 gzipped) when you only need the regular focusTrap and don't need to pierce the shadowDOM.\n\nIf your project is already using the `deepFocusTrap` class in other places you are already going to import the extra dependency so you can import the `focusTrap` class from the main module (i.e. `import { focusTrap } from 'deep-focus-trap'`) or you can use the `deepFocusTrap` class and set the `config.deep` option to `false`. Like so:\n\n``` javascript\nimport { deepFocusTrap } from 'deep-focus-trap';\n\nlet focusTrap = new deepFocusTrap({\n  el: '.modal',\n  deep: false\n});\n```\n\n#### Configuration Options\n\n``` javascript\nimport { deepFocusTrap } from 'deep-focus-trap';\nconst modal = document.querySelector('.modal');\n\nlet focusTrap = new deepFocusTrap({\n  el: modal, // or '.modal', Required option - A selector or element used to trap focus within\n  deep: false, //default: true - When set to false focusTrap will not peirce the Shadow DOM.\n  returnFocus: false, //default: true - An option when set to true returns focus upon deactivation to the last element that had focus before the trap was activated. \n  focusElement: document.querySelector('a.first-focus'), // An element to focus on as soon as the focus trap is activated.\n  includeActiveElement: true, //default: false -  Includes element currently in focus when focusTrap is activated within the focusable elements.\n  unordered: true, //default: false - Allows for elements to be in an order in the dom. Then follows the order of appearance in the focusableElements array instead.\n  escCallback: function(){ // A callback to be called when the user presses the escape key. Note his automatically calls deactivate() after escCallback\n    modal.style.display = 'none';\n  }\n});\n\n```\n**Note: the* `focusTrap` *class doesn't have the* `deep` *option*\n\n#### Using UMD version via CDN\n If you want to use via deep-focus-trap via the `script` tag. We recommend using the UMD version as its more widely supported (You can also use the ES module version using the `type=\"module` attribute.\") You can find the CDN scripts [here](https://www.jsdelivr.com/package/npm/deep-focus-trap?path=dist)\n\nIn using the UMD version  you wont import the module but just copy the script tag:\n``` html\n\u003cscript src=\"/deep-focus-trap.umd.js\"\u003e\u003c/script\u003e\n```\n\nOr if you want the basic version (doesn't pierce the shadow DOM) \n\n``` html\n\u003cscript src=\"/focus-trap.umd.js\"\u003e\u003c/script\u003e\n```\n\nThen to use. Use the `focusTrap` or `deepFocusTrap` function (umd exports to the window)\n\n``` javascript\nconst focusTrap = deepFocusTrap({\n  el: '.modal',\n  escCallback: () =\u003e { \n    const modal = document.querySelector('.modal');\n    modal.style.display = 'none';\n  }\n})\n```\n\nYou can view the API documentation [here](./docs.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthebeyondgroup%2Fdeep-focus-trap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthebeyondgroup%2Fdeep-focus-trap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthebeyondgroup%2Fdeep-focus-trap/lists"}