{"id":25833371,"url":"https://github.com/jonomacc/roving-grid-ux","last_synced_at":"2026-05-13T04:42:30.491Z","repository":{"id":187543772,"uuid":"674356116","full_name":"JonoMacC/roving-grid-ux","owner":"JonoMacC","description":"Adds keyboard grid-based navigation to a DOM context","archived":false,"fork":false,"pushed_at":"2023-08-16T14:17:44.000Z","size":474,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-01T22:18:25.454Z","etag":null,"topics":["grid-navigation","keyboard-navigation","keyboard-ux","roving-focus"],"latest_commit_sha":null,"homepage":"https://roving-grid.netlify.app/","language":"JavaScript","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/JonoMacC.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-08-03T18:41:18.000Z","updated_at":"2024-11-26T13:50:43.000Z","dependencies_parsed_at":"2023-08-11T02:10:06.872Z","dependency_job_id":"ec98dd0d-dd50-495a-b018-5c57c43a0ed7","html_url":"https://github.com/JonoMacC/roving-grid-ux","commit_stats":null,"previous_names":["jonomacc/roving-grid-ux"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonoMacC%2Froving-grid-ux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonoMacC%2Froving-grid-ux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonoMacC%2Froving-grid-ux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonoMacC%2Froving-grid-ux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JonoMacC","download_url":"https://codeload.github.com/JonoMacC/roving-grid-ux/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241263924,"owners_count":19936058,"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":["grid-navigation","keyboard-navigation","keyboard-ux","roving-focus"],"created_at":"2025-02-28T22:47:55.206Z","updated_at":"2026-05-13T04:42:25.459Z","avatar_url":"https://github.com/JonoMacC.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# roving-grid-ux\n\n![npm downloads](https://img.shields.io/npm/dt/roving-grid-ux)\n![npm latest](https://img.shields.io/npm/v/roving-grid-ux)\n![npm license](https://img.shields.io/npm/l/roving-grid-ux)\n![npm bundle size](https://img.shields.io/bundlephobia/min/roving-grid-ux)\n\nAdds keyboard grid-based navigation to a DOM node\n\n**Based on** the work done by [Adam Argyle on roving ux](https://github.com/argyleink/roving-ux)  \n**Try it** at [Roving Grid Playground](https://roving-grid.netlify.app/grid-playground) and [Glyph Browser](https://roving-grid.netlify.app/glyph-browser)\n\n## Features\n\n- Rtl support\n- Customizable key-bindings (W, A, S, D ? 👀)\n- Configurable wrapping behavior between rows\n- Keeps focus when DOM changes (add or remove nodes)\n- Updates when children are programmatically focused by an external component\n- Children are focused by `pointerdown`\n\n## Use Cases\n\n- Add keyboard navigation to custom components\n- Prototype a game or custom interaction pattern\n\n## Installation\n\n```bash\nnpm i roving-grid-ux\n```\n\nCDN: \u003chttps://cdn.skypack.dev/roving-grid-ux\u003e\n\n## Importing\n\n```javascript\n// import from CDN\nimport { rovingGrid } from \"https://cdn.skypack.dev/roving-grid-ux\";\n\n// import roving grid from npm\nimport { rovingGrid } from \"roving-grid-ux\";\n\n// import roving grid and updater from npm\nimport { rovingGrid, updateRover } from \"roving-grid-ux\";\n```\n\n## API\n\n```javascript\nrovingGrid({\n  element: node,    // container that manages focus\n  target: \".cell\",  // query selector for focusable children\n  wrap: false,      // ? whether focus wraps from row to row\n  VKMap: {}         // ? custom keybindings for navigating the grid\n})\n\nupdateRover(\n  element: node,    // roving container to be updated\n  {\n    wrap: true      // ? updated wrap property\n    VKMap: {}       // ? updated keybindings\n  }\n)\n```\n\n### Custom key bindings interface\n\n```javascript\n/**\n * @typedef {string} KeyCombo - A `+` delimited key combination (e.g. `Ctrl+Home`)\n */\n\n/**\n * @typedef {Object} VKMap - A map between virtual keys and key combinations\n * @property {KeyCombo[]} [TOP_LEFT] - The top left key combination\n * @property {KeyCombo[]} [TOP] - The top key combination\n * @property {KeyCombo[]} [TOP_RIGHT] - The top right key combination\n * @property {KeyCombo[]} [UP] - The up key combination\n * @property {KeyCombo[]} [DOWN] - The down key combination\n * @property {KeyCombo[]} [HOME] - The home key combination\n * @property {KeyCombo[]} [END] - The end key combination\n * @property {KeyCombo[]} [LEFT] - The left key combination\n * @property {KeyCombo[]} [RIGHT] - The right key combination\n * @property {KeyCombo[]} [BOTTOM_LEFT] - The bottom left key combination\n * @property {KeyCombo[]} [BOTTOM] - The bottom key combination\n * @property {KeyCombo[]} [BOTTOM_RIGHT] - The bottom right key combination\n *\n */\n```\n\n- Directional keys for horizontal movements are swapped for Rtl (Home and End keys excepted)\n- Multiple keys can be bound to a virtual key. Use JavaScript `Event.key` names.\n- Key combinations should be in order: Ctrl (^), Alt (⌥), Shift (⇧), Meta (⌘).\n\n## Virtual Key Positions\n\nAny of the below positions in a grid can be mapped to a virtual key.  \n![7x7 grid denoting virtual key positions Top Left, Top, Top Right, Up, Home, Left, Right, End, Down, Bottom Left, Bottom, Bottom Right, relative to the current position](/assets/grid-positions.svg)\n\nIf no custom keybindings are provided, the following defaults are used:\n\n| Virtual Key | Key Combinations         |\n| ----------- | ------------------------ |\n| TOP         | Ctrl+Home, Meta+ArrowUp  |\n| BOTTOM      | Ctrl+End, Meta+ArrowDown |\n| UP          | ArrowUp                  |\n| DOWN        | ArrowDown                |\n| HOME        | Home, Meta+ArrowLeft     |\n| END         | End, Meta+ArrowRight     |\n| LEFT        | ArrowLeft                |\n| RIGHT       | ArrowRight               |\n\n## Programmatic Focus\n\nA custom location can be focused by calling its `focus` method. The grid will update its internal representation of the focused element.\n\n## Example Usage\n\n```javascript\nimport { rovingGrid } from \"roving-grid-ux\";\n\nrovingGrid({\n  element: document.querySelector(\"#grid\"),\n  target: \".cell\",\n});\n```\n\n```javascript\nimport { rovingGrid, updateRover } from \"roving-grid-ux\";\n\ndocument.querySelectorAll(\".glyph-grid\").forEach((grid) =\u003e {\n  rovingGrid({\n    element: grid,\n    target: \".glyph\",\n  });\n});\n```\n\n## Limitations\n\nDoes not support virtual focus (e.g. `aria-activedescendant`), so not suitable\nfor composite widgets where focus must remain on one element while keeping the\ngrid navigable via keyboard (a ComboBox with a grid popup... 🤔).\n\nDoes not handle selection, you will have to bring your own selection logic.\n\n`Tab` moves focus out of the container; this is intentional so that keyboard\nnavigation is efficient. However, spreadsheets generally mix tabbed navigation\nwith ←, →, ↑, ↓ navigation, so this may not be good for prototyping that type\nof component.\n\n`PageUp` and `PageDown` do not have a default virtual key. If you need these to move focus you will need to implement it yourself.\n\nGrid items must be sequential in the DOM (i.e. no voids). For inaccessible items, use `disabled` or `inert` items.\n\n## Caution\n\nKeyboard grid navigation is not common outside of default controls or data\ntables. Consider your use case, users, and authoring practices when setting up\na keyboard navigable grid.\n\n## Learn\n\n[ARIA grid interaction pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonomacc%2Froving-grid-ux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonomacc%2Froving-grid-ux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonomacc%2Froving-grid-ux/lists"}