Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ngneat/hotkeys
🤖 A declarative library for handling hotkeys in Angular applications
https://github.com/ngneat/hotkeys
angular hotkeys shortcuts
Last synced: about 1 month ago
JSON representation
🤖 A declarative library for handling hotkeys in Angular applications
- Host: GitHub
- URL: https://github.com/ngneat/hotkeys
- Owner: ngneat
- License: mit
- Created: 2020-04-13T10:43:05.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-03-20T07:34:37.000Z (6 months ago)
- Last Synced: 2024-05-01T11:39:42.851Z (5 months ago)
- Topics: angular, hotkeys, shortcuts
- Language: TypeScript
- Homepage: https://netbasal.com/diy-keyboard-shortcuts-in-your-angular-application-4704734547a2
- Size: 1.35 MB
- Stars: 326
- Watchers: 8
- Forks: 17
- Open Issues: 31
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-angular - hotkeys - A declarative library for handling hotkeys in Angular applications. (Table of contents / Third Party Components)
README
[]()
[]()
[]()
[](https://github.com/prettier/prettier)
[](#contributors-)
[](https://github.com/ngneat/)
[]()
> Shortcut like a pro!
A declarative library for handling hotkeys in Angular applications.
Web apps are getting closer and closer to be desktop-class applications. With this in mind, it makes sense to add hotkeys for those power users that are looking to navigate their favorite websites using hotkeys just as they do on their regular native apps. To help you have a better experience we developed Hotkeys.
## Features
- ✅ Support Element Scope
- ✅ Support Global Listeners
- ✅ Platform Agnostic
- ✅ Hotkeys Cheatsheet
## Table of Contents
- [Compatibility](#compatibility-with-angular-versions)
- [Installation](#installation)
- [Usage](#usage)
- [FAQ](#faq)
## Compatibility with Angular Versions
| @ngneat/hotkeys | Angular |
|-----------------|---------|
| 3.x.x | >=17.2 |
| 2.x.x | >=16 |
| 1.3.x | >=14 |
| 1.2.x | <=13 |
## Installation
`npm install @ngneat/hotkeys`
## Usage
### Module
Add `HotkeysModule` in your `AppModule`:
```ts
import { HotkeysModule } from '@ngneat/hotkeys';
@NgModule({
imports: [HotkeysModule]
})
export class AppModule {}
```
### Standalone
Add `HotkeysService` in the standalone components :
```ts
@Component({
standalone: true,
imports: [HotkeysDirective],
})
export class AppComponent {}
```
Now you have two ways to start adding shortcuts to your application:
## Hotkeys Directive
```html
```
> Hotkeys take care of transforming keys from macOS to Linux and Windows and vice-versa.
Additionally, the directive accepts three more `input`s:
- `hotkeysGroup` - define the group name.
- `hotkeysDescription` - add a description.
- `hotkeysOptions` - See [Options](#options)
- `isSequence` - indicate hotkey is a sequence of keys.
For example:
```html
console.log('Hotkey', e));
this.hotkeys.addSequenceShortcut({ keys: 'g>i' }).subscribe(e => console.log('Hotkey', e));
}
}
```
### Options
There are additional properties we can provide:
```ts
interface Options {
// The group name
group: string;
// hotkey target element (defaults to `document`)
element: HTMLElement;
// The type of event (defaults to `keydown`)
trigger: 'keydown' | 'keyup';
// Allow input, textarea and select as key event sources (defaults to []).
// It can be 'INPUT', 'TEXTAREA', 'SELECT' or 'CONTENTEDITABLE'.
allowIn: AllowInElement[];
// hotkey description
description: string;
// Included in the shortcut list to be display in the help dialog (defaults to `true`)
showInHelpMenu: boolean;
// Whether to prevent the default behavior of the event. (defaults to `true`)
preventDefault: boolean;
}
```
### `onShortcut`
Listen to any registered hotkey. For example:
```ts
const unsubscribe = this.hotkeys.onShortcut((event, key, target) => console.log('callback', key));
// When you're done listening, unsubscribe
unsubscribe();
```
### `registerHelpModal`
Display a help dialog listing all visible hotkeys:
```ts
import { NgbModal } from '@ng-bootstrap/ng-bootstrap';
import { HotkeysHelpComponent, HotkeysService } from '@ngneat/hotkeys';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.css']
})
export class AppComponent implements AfterViewInit {
constructor(private hotkeys: HotkeysService, private dialog: NgbModal) {}
ngAfterViewInit() {
this.hotkeys.registerHelpModal(() => {
const ref = this.modalService.open(HotkeysHelpComponent, { size: 'lg' });
ref.componentInstance.title = 'Custom Shortcuts Title';
ref.componentInstance.dismiss.subscribe(() => ref.close());
});
}
}
```
It accepts a second input that allows defining the hotkey that should open the dialog. The default shortcut is `Shift + ?`. Here's how `HotkeysHelpComponent` looks like:
```
```
You can also provide a custom component. To help you with that, the service exposes the `getShortcuts` method.
### `removeShortcuts`
Remove previously registered shortcuts.
```ts
// Remove a single shortcut
this.hotkeys.removeShortcuts('meta.a');
// Remove several shortcuts
this.hotkeys.removeShortcuts(['meta.1', 'meta.2']);
```
### `setSequenceDebounce`
Set the number of milliseconds to debounce a sequence of keys
```ts
this.hotkeys.setSequenceDebounce(500);
```
## Hotkeys Shortcut Pipe
The `hotkeysShortcut` formats the shortcuts when presenting them in a custom help screen:
```html
```
The pipe accepts and additional parameter the way key combinations are separated. By default, the separator is `+`. In the following example, a `-` is used as separator.
```html
```
## Allowing hotkeys in form elements
By default, the library prevents hotkey callbacks from firing when their event originates from an `input`, `select`, or `textarea` element or any elements that are contenteditable. To enable hotkeys in these elements, specify them in the `allowIn` parameter:
```ts
import { HotkeysService } from '@ngneat/hotkeys';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.css']
})
export class AppComponent {
constructor(private hotkeys: HotkeysService) {}
ngOnInit() {
this.hotkeys
.addShortcut({ keys: 'meta.a', allowIn: ['INPUT', 'SELECT', 'TEXTAREA', 'CONTENTEDITABLE'] })
.subscribe(e => console.log('Hotkey', e));
}
}
```
It's possible to enable them in the template as well:
```html
Carlos Vilacha
💻 🖋 📖
Netanel Basal
📝 💻 📖 🤔
Álvaro Martínez
💻 📖
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!