{"id":44986843,"url":"https://github.com/microbit-foundation/keyosd","last_synced_at":"2026-02-18T20:00:55.269Z","repository":{"id":324919539,"uuid":"1099088171","full_name":"microbit-foundation/keyosd","owner":"microbit-foundation","description":"Display keystrokes and shortcuts in an on-screen overlay inside a web app ","archived":false,"fork":false,"pushed_at":"2025-11-18T16:05:16.000Z","size":83,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-18T16:46:28.026Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://microbit-foundation.github.io/keyosd/","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/microbit-foundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"2025-11-18T14:49:56.000Z","updated_at":"2025-11-18T16:02:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/microbit-foundation/keyosd","commit_stats":null,"previous_names":["microbit-foundation/keyosd"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/microbit-foundation/keyosd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fkeyosd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fkeyosd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fkeyosd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fkeyosd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microbit-foundation","download_url":"https://codeload.github.com/microbit-foundation/keyosd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fkeyosd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29593911,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T18:54:29.675Z","status":"ssl_error","status_checked_at":"2026-02-18T18:50:50.517Z","response_time":162,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-02-18T20:00:27.991Z","updated_at":"2026-02-18T20:00:55.259Z","avatar_url":"https://github.com/microbit-foundation.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KeyOSD\n\nDisplay keystrokes and shortcuts in an on-screen overlay inside a web app.\n\n![\"Screen capture showing hello world Cmd+C Cmd+V being displayed as they are typed\"](https://github.com/user-attachments/assets/fafe1542-05e1-4ac5-a0ed-604d9ba2376e)\n\n[Try it now](https://microbit-foundation.github.io/keyosd/)\n\nBuilt for user testing keyboard interactions in an environment where installing\ntools like [KeyCastr](https://github.com/keycastr/keycastr) is not viable.\n\nThis utility is maintained by the Micro:bit Educational Foundation as time\npermits. It is not a core project and comes with no support commitments.\n\nYou can integrate it in your app or user testing environment with a simple script tag or for ad hoc testing use a bookmarklet to run it in a page you don't control.\n\n## Features\n\n- Shows recent keystrokes and keyboard shortcuts\n- Compact visualization inspired by [KeyCastr](https://github.com/keycastr/keycastr)'s Svelte-mode\n- Draggable to move away from user interface elements as needed\n\n## Limitations\n\n### Mobile platforms\n\nKeyOSD relies on browser keyboard events (`keydown`/`keyup`) which are not consistently fired by virtual/on-screen keyboards on mobile devices. This means you may not see key output when typing on phones or tablets in inputs or contenteditable elements.\n\n### Keyboard layout support\n\nBrowser key events expose a key `code` in terms of a US ASCII QWERTY keyboard and a `key` property that exposes the resulting character.\n\nGenerally it's preferable to use `key`. But this presents a challenge with shortcuts like Option+C for which the key is `ç` but you might reasonably expect to see ⌥C.\n\nSo, for normal typing we use `key`. When modifiers are used, we use `code` then map it to the corresponding key using [KeyboardLayoutMap](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardLayoutMap) when available, otherwise a QWERTY-specific default mapping.\n\nThere might be a better compromise position here and feedback is welcome from users with international or non-QWERTY layouts.\n\n## Usage\n\n### Bookmarklet\n\nBookmarklet to copy paste as the bookmark URL ([what's a bookmarklet?](https://en.wikipedia.org/wiki/Bookmarklet)):\n\n```\njavascript:(function() { document.body.appendChild(document.createElement(\"script\")).src = \"https://microbit-foundation.github.io/keyosd/v0/keyosd.js\"})()\n```\n\nNote you might hit [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) errors. There's nothing that can be done with this project in that case if you can't modify the app.\n\n**⚠️ This runs JavaScript from this project with full access to your current browser tab**\n\n### Script tag\n\nInclude the script in your HTML file. KeyOSD will automatically initialize:\n\n```html\n\u003cscript src=\"https://microbit-foundation.github.io/keyosd/v0/keyosd.js\"\u003e\u003c/script\u003e\n```\n\n#### Positioning\n\nConfigure the overlay position using data attributes on the script tag:\n\n```html\n\u003c!-- Default: bottom-right corner, 16px offset --\u003e\n\u003cscript src=\"https://microbit-foundation.github.io/keyosd/v0/keyosd.js\"\u003e\u003c/script\u003e\n\n\u003c!-- Custom position: 215px from right, 4px from bottom --\u003e\n\u003cscript\n  src=\"https://microbit-foundation.github.io/keyosd/v0/keyosd.js\"\n  data-anchor=\"bottom-right\"\n  data-x-offset=\"215\"\n  data-y-offset=\"4\"\n\u003e\u003c/script\u003e\n\n\u003c!-- Top-left corner --\u003e\n\u003cscript\n  src=\"https://microbit-foundation.github.io/keyosd/v0/keyosd.js\"\n  data-anchor=\"top-left\"\n\u003e\u003c/script\u003e\n```\n\nAvailable data attributes:\n\n- `data-anchor`: Corner to anchor to. Options: `\"top-left\"`, `\"top-right\"`, `\"bottom-left\"`, `\"bottom-right\"` (default: `\"bottom-right\"`)\n- `data-x-offset`: Horizontal offset from the anchor edge in pixels (default: `16`)\n- `data-y-offset`: Vertical offset from the anchor edge in pixels (default: `16`)\n\n#### Controlling the instance\n\nThe overlay will appear automatically and start capturing keystrokes. Access the instance via `window.keyosd` if you need to control it:\n\n```javascript\n// Disable/enable\nwindow.keyosd.disable();\nwindow.keyosd.enable();\n\n// Clear display\nwindow.keyosd.clear();\n```\n\n### As a module\n\nInstall the package:\n\n```bash\nnpm install @microbit/keyosd\n```\n\nImport and initialize manually for more control (styles are automatically injected):\n\n```typescript\nimport { KeyOSD } from \"@microbit/keyosd\";\n\n// Initialize with default options\nconst keyosd = new KeyOSD();\n```\n\n### With options\n\n```typescript\nimport { KeyOSD } from \"@microbit/keyosd\";\n\nconst keyosd = new KeyOSD({\n  container: document.body, // Container element (default: document.body)\n  enabled: true, // Start capturing immediately (default: true)\n  anchor: \"bottom-right\", // Corner to anchor to (default: \"bottom-right\")\n  xOffset: 16, // Horizontal offset in pixels (default: 16)\n  yOffset: 16, // Vertical offset in pixels (default: 16)\n});\n```\n\n## API\n\n### Constructor\n\n```typescript\nnew KeyOSD(options?: KeyOSDOptions)\n```\n\n### Methods\n\n#### `enable()`\n\nStart capturing keyboard events.\n\n```typescript\nkeyosd.enable();\n```\n\n#### `disable()`\n\nStop capturing keyboard events and hide the UI.\n\n```typescript\nkeyosd.disable();\n```\n\n#### `clear()`\n\nClear all currently displayed keystrokes.\n\n```typescript\nkeyosd.clear();\n```\n\n#### `destroy()`\n\nRemove the visualization and clean up all event listeners.\n\n```typescript\nkeyosd.destroy();\n```\n\n## Options\n\n```typescript\ninterface KeyOSDOptions {\n  container?: HTMLElement; // Container element (default: document.body)\n  enabled?: boolean; // Start enabled (default: true)\n  anchor?: \"top-left\" | \"top-right\" | \"bottom-left\" | \"bottom-right\"; // Corner to anchor to (default: \"bottom-right\")\n  xOffset?: number; // Horizontal offset from anchor edge in pixels (default: 16)\n  yOffset?: number; // Vertical offset from anchor edge in pixels (default: 16)\n}\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Start development server\nnpm run dev\n\n# Build library\nnpm run build\n```\n\n## License\n\nThis software is under the MIT open source license.\n\n[SPDX-License-Identifier: MIT](LICENSE)\n\nWe use dependencies via the NPM registry as specified by the package.json file under common Open Source licenses.\n\nFull details of each package can be found by running `license-checker`:\n\n```bash\n$ npx license-checker --direct --summary --production\n```\n\nOmit the flags as desired to obtain more detail.\n\n## Code of conduct\n\nTrust, partnership, simplicity and passion are our core values we live and\nbreathe in our daily work life and within our projects. Our open-source\nprojects are no exception. We have an active community which spans the globe\nand we welcome and encourage participation and contributions to our projects\nby everyone. We work to foster a positive, open, inclusive and supportive\nenvironment and trust that our community respects the micro:bit code of\nconduct. Please see our [code of conduct](https://microbit.org/safeguarding/)\nwhich outlines our expectations for all those that participate in our\ncommunity and details on how to report any concerns and what would happen\nshould breaches occur.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrobit-foundation%2Fkeyosd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrobit-foundation%2Fkeyosd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrobit-foundation%2Fkeyosd/lists"}