{"id":13466660,"url":"https://github.com/jsakamoto/Toolbelt.Blazor.Hotkeys","last_synced_at":"2025-03-26T00:31:19.749Z","repository":{"id":41565952,"uuid":"149760233","full_name":"jsakamoto/Toolbelt.Blazor.HotKeys","owner":"jsakamoto","description":"This is a class library that provides configuration-centric keyboard shortcuts for your Blazor WebAssembly (client-side) apps.","archived":false,"fork":false,"pushed_at":"2023-01-22T06:12:31.000Z","size":5085,"stargazers_count":111,"open_issues_count":6,"forks_count":14,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-22T12:12:01.237Z","etag":null,"topics":["blazor-webassembly","hotkeys"],"latest_commit_sha":null,"homepage":"https://jsakamoto.github.io/Toolbelt.Blazor.HotKeys/","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jsakamoto.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":"2018-09-21T12:27:27.000Z","updated_at":"2025-03-05T12:17:06.000Z","dependencies_parsed_at":"2023-01-31T10:30:50.052Z","dependency_job_id":null,"html_url":"https://github.com/jsakamoto/Toolbelt.Blazor.HotKeys","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsakamoto%2FToolbelt.Blazor.HotKeys","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsakamoto%2FToolbelt.Blazor.HotKeys/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsakamoto%2FToolbelt.Blazor.HotKeys/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsakamoto%2FToolbelt.Blazor.HotKeys/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jsakamoto","download_url":"https://codeload.github.com/jsakamoto/Toolbelt.Blazor.HotKeys/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245566096,"owners_count":20636390,"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":["blazor-webassembly","hotkeys"],"created_at":"2024-07-31T15:00:47.941Z","updated_at":"2025-03-26T00:31:19.118Z","avatar_url":"https://github.com/jsakamoto.png","language":"C#","funding_links":[],"categories":["Libraries \u0026 Extensions"],"sub_categories":["Tools \u0026 Utilities"],"readme":"# [⚠️Deprecated] Blazor HotKeys [![NuGet Package](https://img.shields.io/nuget/v/Toolbelt.Blazor.HotKeys.svg)](https://www.nuget.org/packages/Toolbelt.Blazor.HotKeys/)\n\n\u003e **Warning**  \n\u003e **\"Blazor HotKeys\" has been deprecated. Its official successor is [\"Blazor HotKeys 2\"!](https://github.com/jsakamoto/Toolbelt.Blazor.HotKeys2/)**\n\nUnfortunately, the design of the \"Blazor HotKeys\" is not so good because I'm not so clever and didn't have enough knowledge when I started developing the \"Blazor HotKeys\". The \"Blazor HotKeys\" depended on the `keyCode` code property of the keyboard event argument that was deprecated now. Even though it is, I've been refining the \"Blazor HotKeys\" with keeping the compatibility on a binary level. But it is about to reach the limit to improve these days. Due to it having depended on the `keyCode` property at the project start time, there are so many hacky codes, and the API syntax of the \"Blazor HotKeys\" is not smart.\n\nFor the reasons above, I decided to create a hotkeys library again from scratch. The achievement is the \"Blazor HotKeys 2\".\n\nThe API syntax of the \"Blazor HotKeys 2\" is not so different from the \"Blazor HotKeys\". But the API of the \"Blazor HotKeys 2\" treat the `key` and the `code` property of the keyboard event straight. This design should ensure clarity from developers. I hope many Blazor developers will be happy migrating from the \"Blazor HotKeys\" to the \"Blazor Hotkeys 2\".\n\n\u003cdetails\u003e\n\u003csummary\u003eFor more detail of Blazor HotKeys\u003c/summary\u003e\n\n## Summary\n\nThis is a class library that provides configuration-centric keyboard shortcuts for your Blazor apps.\n\n![movie](https://raw.githubusercontent.com/jsakamoto/Toolbelt.Blazor.HotKeys/master/.assets/movie-001.gif)\n\n- [Live demo](https://jsakamoto.github.io/Toolbelt.Blazor.HotKeys/)\n\nYou can declare associations of keyboard shortcut and callback action, like this code:\n\n```csharp\n// The method \"OnSelectAll\" will be invoked \n//  when the user typed Ctrl+A key combination.\nthis.HotKeysContext = this.HotKeys.CreateContext()\n  .Add(ModKeys.Ctrl, Keys.A, OnSelectAll)\n  .Add(...)\n  ...;\n```\n\nThis library was created inspired by [\"angular-hotkeys\"](https://github.com/chieffancypants/angular-hotkeys).\n\n## Supported Blazor versions\n\n\"Blazor HotKeys\" ver.9.x or later supports both Blazor WebAssembly and Blazor Server.\n\nSupported Blazor versions are as below.\n\n- v.3.1 (including previews and release candidates.)\n- v.3.2 (including previews and release candidates.)\n- v.5.0 (including previews and release candidates.)\n- v.6.0 (including previews and release candidates.)\n\n## How to install and use?\n\n### 1. Installation and Registration\n\n**Step.1** Install the library via NuGet package, like this.\n\n```shell\n\u003e dotnet add package Toolbelt.Blazor.HotKeys\n```\n\n**Step.2** Register \"HotKeys\" service into the DI container.\n\nIf the Blazor version of the project is ver.3.1 preview 4 or earlier, you should add the code into the `ConfigureService` method in the `Startup` class of your Blazor application.\n\n```csharp\nusing Toolbelt.Blazor.Extensions.DependencyInjection; // 1. Add this line\n...\npublic class Startup\n{\n  public void ConfigureServices(IServiceCollection services)\n  {\n    services.AddHotKeys(); // 2. Add this line\n    ...\n```\n\nIf the Blazor version of the project is ver.3.2 preview 1 or later, you should add the code into your `Main` method in the `Program` class of your Blazor application.\n\n```csharp\nusing Toolbelt.Blazor.Extensions.DependencyInjection; // 1. Add this line\n...\npublic class Program\n{\n  public static async Task Main(string[] args)\n  {\n    var builder = WebAssemblyHostBuilder.CreateDefault(args);\n    ...\n    builder.Services.AddHotKeys(); // 2. Add this line\n    ...\n```\n\n### 2. Usage in your Blazor component (.razor)\n\n**Step.1** Implement `IDisposable` interface to the component.\n\n```razor\n@implements IDisposable @* \u003c- Add this at top of the component.  *@\n...\n\n@code {\n  ...\n  public void Dispose() // \u003c- Add \"Dispose\" method.\n  {\n  }\n}\n```\n\n**Step.2** Open the `Toolbelt.Blazor.HotKeys` namespace, and inject the `HotKeys` service into the component.\n\n```razor\n@implements IDisposable\n@using Toolbelt.Blazor.HotKeys @* 1. Add this *@\n@inject HotKeys HotKeys @* 2. Add this *@\n...\n```\n\n**Step.3** Invoke `CreateContext()` method of the `HotKeys` service instance to create and activate hot keys entries at startup of the component such as `OnInitialized()` method.\n\nYou can add the combination with key and action to the `HotKeysContext` object that is returned from `CreateContext()` method, using `Add()` method.\n\nPlease remember that you have to keep the `HotKeys Context` object in the component field.\n\n```csharp\n@code {\n\n  HotKeysContext HotKeysContext;\n\n  protected override void OnInitialized()\n  {\n    this.HotKeysContext = this.HotKeys.CreateContext()\n      .Add(ModKeys.Ctrl|ModKeys.Shift, Keys.A, FooBar, \"do foo bar.\")\n      .Add(...)\n      ...;\n  }\n\n  void FooBar() // \u003c- This will be invoked when Ctrl+Shift+A typed.\n  {\n    ...\n  }\n}\n```\n\n\u003e _Note.1:_ You can also specify the async method to the callback action argument.\n\n\u003e _Note.2:_ The method of the callback action can take an argument which is `HotKeyEntry` object.\n\n\n**Step.4** Destroy the `HotKeysContext` when the component is disposing, in the `Dispose()` method of the component.\n\n```csharp\n@code {\n  ...\n  public void Dispose()\n  {\n    this.HotKeysContext.Dispose(); // 1. Add this\n  }\n}\n```\n\nThe complete source code (.razor) of this component is bellow.\n\n```csharp\n@page \"/\"\n@implements IDisposable\n@using Toolbelt.Blazor.HotKeys\n@inject HotKeys HotKeys\n\n@code {\n\n  HotKeysContext HotKeysContext;\n\n  protected override void OnInitialized()\n  {\n    this.HotKeysContext = this.HotKeys.CreateContext()\n      .Add(ModKeys.Ctrl|ModKeys.Shift, Keys.A, FooBar, \"do foo bar.\");\n  }\n\n  void FooBar()\n  {\n    // Do something here.\n  }\n\n  public void Dispose()\n  {\n    this.HotKeysContext.Dispose();\n  }\n}\n```\n\n### 3. Appendix - How to enable / disable hotkeys depending on which element has focus\n\nYou can specify enabling/disabling hotkeys depending on which element has focus when hotkeys registration via a combination of the `Exclude` flags that are optional 5th argument of the `HotKeysContext.Add()` method.\n\nBy default, the `Exclude` flags argument is the following combination.\n\n```csharp\nExclude.InputText | Exclude.InputNonText | Exclude.TextArea\n```\n\nThis means, by default, hotkeys are disabled when the focus is in an `\u003cinput\u003e` (with any `type`) or `\u003ctextarea\u003e` element.\n\nIf you want to enable hotkeys even when an `\u003cinput type=\"text\"/\u003e` is focused, you can do it as below.\n\n```csharp\n... this.HotKeys.CreateContext()\n  .Add(ModKeys.None, Keys.A, OnKeyDownA, \"...\", \n    // 👇 Specify the 5th argument.\n    exclude: Exclude.InputNonText | Exclude.TextArea)\n  ...\n```\n\nAnd you can specify the `Exclude.ContentEditable` to register the unavailable hotkey when any \"contenteditable\" applied elements are focused.\n\n\n## Limitations\n\n### No \"Cheat Sheet\"\n\nUnlike [\"angular-hotkeys\"](https://github.com/chieffancypants/angular-hotkeys), this library doesn't provide \"cheat sheet\" feature, at this time.\n\nInstead, the `HotKeysContext` object provides `Keys` property, so you can implement your own \"Cheat Sheet\" UI, like this code:\n\n```razor\n\u003cul\u003e\n    @foreach (var key in this.HotKeysContext.Keys)\n    {\n        \u003cli\u003e@key\u003c/li\u003e\n    }\n\u003c/ul\u003e\n```\n\nThe rendering result:\n\n```\n- Shift+Ctrl+A: do foo bar.\n- ...\n```\n\n## Release Note\n\n[Release notes](https://github.com/jsakamoto/Toolbelt.Blazor.HotKeys/blob/master/RELEASE-NOTES.txt)\n\n## License\n\n[Mozilla Public License Version 2.0](https://github.com/jsakamoto/Toolbelt.Blazor.HotKeys/blob/master/LICENSE)\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsakamoto%2FToolbelt.Blazor.Hotkeys","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjsakamoto%2FToolbelt.Blazor.Hotkeys","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsakamoto%2FToolbelt.Blazor.Hotkeys/lists"}