{"id":17113632,"url":"https://github.com/flamefork/freefocus","last_synced_at":"2025-10-29T20:31:58.558Z","repository":{"id":10286839,"uuid":"12404556","full_name":"Flamefork/freefocus","owner":"Flamefork","description":"\"Visual\", no-hassle navigation in HTML using IR remote / arrow keys","archived":false,"fork":false,"pushed_at":"2016-02-12T23:19:04.000Z","size":97,"stargazers_count":18,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-13T04:05:20.827Z","etag":null,"topics":["focus","focuspoint","keyboard-navigation"],"latest_commit_sha":null,"homepage":"","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/Flamefork.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}},"created_at":"2013-08-27T11:45:14.000Z","updated_at":"2019-11-18T09:42:00.000Z","dependencies_parsed_at":"2022-09-04T22:02:13.948Z","dependency_job_id":null,"html_url":"https://github.com/Flamefork/freefocus","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Flamefork%2Ffreefocus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Flamefork%2Ffreefocus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Flamefork%2Ffreefocus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Flamefork%2Ffreefocus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Flamefork","download_url":"https://codeload.github.com/Flamefork/freefocus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248661707,"owners_count":21141450,"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":["focus","focuspoint","keyboard-navigation"],"created_at":"2024-10-14T17:11:15.931Z","updated_at":"2025-10-29T20:31:58.459Z","avatar_url":"https://github.com/Flamefork.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FreeFocus\n\n\"Visual\", no-hassle navigation in HTML using IR remote / arrow keys.\n\nIntended for HTML5 applications where arrow keys or IR remote control is essential:\nSmartTV applications, set-top box UI, etc.\n\nMany current devices are able to use mouse pointer: LG Magic Remote, Samsung Smart Touch Remote,\nUSB Wireless mouse, etc. Implementing two different navigation schemes is hard.\n\nFreeFocus lets you stick with the easy one (pointer device, we used to it in Web UI)\nand handles the hard one (direction keys) in the most unobtrusive way.\n\nNo need to operate separate logical navigation structures (lists, grids, etc).\nJust use HTML for UI and let FreeFocus navigate it \"visually\" — using positions of\nfocusable elements on page. If user pressed \"right\", just move focus to focusable\nelement placed to the right of the current focused one. It's that easy.\n\nIt can be used as a polyfill for [CSS3 UI `nav-*` directional focus navigation](http://www.w3.org/TR/css3-ui/#nav-dir).\n\nUses [W3C WICD Current Focus Point Algorithm](http://www.w3.org/TR/WICD/#current-focus-point-algorithm) for focus traversal.\n\n## Download\n\nVanillaJS core:\n\n- [Core](https://raw.github.com/Flamefork/freefocus/master/freefocus.js)\n- [Minified version](https://raw.github.com/Flamefork/freefocus/master/freefocus.min.js)\n\njQuery plugin:\n\n- [Core (plugin dependency)](https://raw.github.com/Flamefork/freefocus/master/freefocus.js)\n- [Plugin](https://raw.github.com/Flamefork/freefocus/master/jquery.freefocus.js)\n- [Minified merged version](https://raw.github.com/Flamefork/freefocus/master/jquery.freefocus.min.js)\n\n## Getting Started\n\n```html\n\u003cscript src=\"jquery.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"jquery.freefocus.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n$(function() {\n  $.freefocus({hoverFocus: true});\n});\n\u003c/script\u003e\n```\n\nThat's it, now you have it all set up.\n\n## Core Documentation\n\nTBD, sorry. See [Source](https://github.com/Flamefork/freefocus/blob/master/freefocus.js) for now.\n\n## jQuery Plugin Documentation\n\n### `$.freefocus({options...}, {moveOptions...})`\n\nSet up keyboard navigation.\n\nOptions:\n\n- `focusedSelector` - selector for currently focused (or active) element. default: `':focus'`\n- `hoverFocus` - focus target elements on mouse enter. default: `false`\n- `throttle` - throttle key input for specified time (in milliseconds).\n  You'll need underscore.js included to use this feature. default: `false`\n\nMove options are passed to [`$.fn.freefocus`](#fnfreefocusoptions)\n\n\n### `$.freefocus('remove')`\n\nRemove previously set keyboard navigation.\n\n\n### `$.freefocus('cache', options)`\n\nCompute and cache dimension information for focusable elements. Options: `focusablesSelector`, `focusablesFilter`, `focusablesContext`\n\n\n### `$.fn.freefocus({options...})`\n\nMove \"focus\" from active element to one of the targets by triggering specified event.\n\nOptions:\n\n- `move` - move direction: `left` | `right` | `up` | `down`. no default\n- `focusablesSelector` - selector for navigation targets. default: a long selector describing all focusable options in web browsers.\n  You may want to provide something shorter to improve performance or use `:focusable` from jQuery UI.\n- `focusablesFilter` — selector that filters targets after they were selected using `focusablesSelector`.\n  Separated for performance reasons. default: `':visible'`\n- `focusablesContext` — element or selector, conext for navigation targets search. default: `undefined`\n- `targets` - jQuery object containing \"focusable\" elements. no default\n  You should supply either focusablesSelector/Filter (preferred if you use nav-*) or explicit targets.\n- `debug` - print weighting information over targets. default: `false`\n- `trigger` - event to trigger on selected target. default: `'focus'`\n- `preTrigger` - event to trigger on selected target before the `trigger` one. default: `false` (don't trigger)\n  Useful if `trigger` is `focus` to move the next focused element into view to avoid native behavior.\n- `maxDistance` - maximum distance to element to still consider moving to it. default: `Infinity`\n- `cache` - cache dimension information for element. default: `false`\n  You'll need to manually reset cache for moved elements by using `$(element).freefocus('moved')`\n\n\n### `$.fn.freefocus('dimensions')`\n\nGet element dimensions `{top, left, width, height}`. Uses cache, if it's enabled.\n\n\n### `$.fn.freefocus('moved')`\n\nClear cached dimension info for element. Should be triggered for every element that is moved, if using `cache`.\n\n\n### `$.fn.freefocus('nav', hints)`\n\nSet hints (see next chapter for details).\n\nHints argument is either:\n\n- hints object - example: `{ left: 'none', right: '#someId' }`. no default\n- `clear` - special string value, clear all nav hints from the element\n\n\n### nav-* hints\n\nAllows for fine-grained control over focus movements.\nFreeFocus implements [CSS3 UI `nav-*` directional focus navigation](http://www.w3.org/TR/css3-ui/#nav-dir) specification with few differences:\n\n- targeting frames is not supported\n- added special value `none`, which disables focus movement in the specified direction. e.g. `nav-left: none;` means that pressing left arrow does nothing\n- added reading JavaScript counterparts to css properties: `navLeft`, `navRight`, `navUp`, `navDown`. e.g. `domNode.navLeft = '#someId';`\n- full jQuery selector syntax allowed. In case of multiple elements matching the selector, FreeFocus would navigate to the first that is really focusable (using `focusablesSelector` and `focusablesFilter`)\n- if the hint targets multiple elements, FreeFoucs will search for the best target using spacial navigation rules\n- listing multiple hints separated by `;` allows to set priorities: they will be matched in a listed order one by one. first that matches any vaild tagret would be taken\n\nHints could be specified using\n\n- HTML tags `style` attribute: `nav-left`, `nav-right`, `nav-up`, `nav-down`\n- JavaScript counterparts to CSS properties: `navLeft`, `navRight`, `navUp`, `navDown`\n- data attributes: `\u003cbutton data-nav-left=\"selector\"\u003e`\n- FreeFocus API on top of data attributes: `$.fn.freefocus('nav')`\n\n## Changelog\n\n- 0.11.2 Added overwrite argument to `setHint` (`true` by default) \n- 0.11.1 More consistent core API\n- 0.11.0 Extracted the jQuery-less core into `freefocus.js`\n- 0.10.3 Freefocus now logs errors to console and uses safe fallback instead of throwing errors \n- 0.10.2 Fixed `freefocus('cache')`\n- 0.10.1 Removed lots of jQuery calls from code, speedup is imminent\n- 0.10.0 Supported `targets` option to be a function that returns focusable elements instead of using `focusablesSelector` and `focusablesFilter`\n- 0.9.0 Freefocus returns focus target (or self if no target found) instead of self\n- 0.8.8 Optimized custom event triggering\n- 0.8.7 Element dimensions doesn't include border anymore\n- 0.8.6 Allowed nav hints to target outside `focusablesContext`\n- 0.8.5 Fixed contiguous target navigation\n- 0.8.4 Supported clearing nav hints\n- 0.8.3 Supported merging nav hints\n- 0.8.2 Changed target separator to `;`\n- 0.8.1 Added `data-nav-*` attributes support\n- 0.8.0 Added jQuery syntax support, added `$.fn.freefocus('nav')` method\n- 0.7.0 Added `focusablesContext` option. Moved `focusables*` options from `setupOptions` to `moveOptions`.\n- 0.6.0 Added `focusablesFilter` setup option. Added optional `focusablesSelector` and `focusablesFilter` move options which has better performance over `targets` when used with `nav-*` props.\n- 0.5.4 Added special `none` value for nav-* properties.\n- 0.5.3 Fixed the bug when freefocus tries to focus invisible element if it's found by CSS3 directional props.\n- 0.5.2 Added `preTrigger` event.\n- 0.5.1 Added selector parameter to caching function. Cleaned up code a bit.\n- 0.5.0 Added support for caching focusable elements dimensions. Speeds up navigation on slow devices.\n- 0.4.2 Fixed using spatial navigation algorithm as a fallback for nav-* properties.\n- 0.4.1 Added maxDistance option. Focus point now stored relative to focused element, so it's consistent even if element is moved / scrolled.\n- 0.4.0 Implemented WICD Current focus point focus navigation algorithm.\n- 0.3.1 Support for non-standard arrow key codes. Added input throttling option (using UnderscoreJS, if available).\n- 0.3.0 Rewritten in vanilla JavaScript for easier maintenance.\n- 0.2.2 Fixed double movement for platforms that already implement spatial navigation.\n- 0.2.1 Added support for navLeft DOM properties in addition to nav-left CSS properties.\n- 0.2.0 Added support for CSS3 UI `nav-*` directional focus navigation properties. Changed naming style from under_scores to camelCase.\n- 0.1.1 Updated minor stuff like readme, packaging, documentation\n- 0.1.0 Initial version\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflamefork%2Ffreefocus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflamefork%2Ffreefocus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflamefork%2Ffreefocus/lists"}