mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-22 16:56:50 +00:00
Update docs for quick bar to include new hotkeys, new enable/disable … (#15438)
This commit is contained in:
parent
2fc7a3623b
commit
d8803387de
@ -5,7 +5,7 @@ description: "Dialog for quickly accessing entities or running commands."
|
||||
|
||||
The "Quick Bar" allows you to quickly look up entities or run commands without needing to navigate away from your current view (Similar to the "quick open" feature in VS Code, Chrome Developer Tools, etc).
|
||||
|
||||
It can be launched in the frontend using [hotkeys](#hotkeys).
|
||||
It can be launched from anywhere in the frontend using [hotkeys](#hotkeys).
|
||||
|
||||
<p class='img'>
|
||||
<img src='/images/docs/quick-bar/quick-bar-demo.gif' alt='Quick Bar'>
|
||||
@ -16,69 +16,109 @@ It can be launched in the frontend using [hotkeys](#hotkeys).
|
||||
|
||||
Type these from anywhere in the application to launch the dialog.
|
||||
|
||||
| Mode | Hotkey (Windows) | Hotkey (macOS)
|
||||
| ------------- | ------------- |------------- |
|
||||
| Entity Filter | Ctrl+P | ⌘+P |
|
||||
| Command | Ctrl+Shift+P | ⌘+Shift+P |
|
||||
| Mode | Hotkey | Switch Modes
|
||||
| ------------- | ------------- | ------------- |
|
||||
| Entity Filter | `e` | Type `>` at start of input to switch to command palette.
|
||||
| Command Palette| `c` | Remove `>` from start of input to switch to entity filter.
|
||||
|
||||
<div class='note'>
|
||||
The application must have "focus" for the hotkey to register. If the dialog doesn't launch, try clicking in an empty area of the application and typing it again.
|
||||
The application must have focus for the hotkey to register. If the dialog doesn't launch, try clicking into an empty part of the main content area of Home Assistant and type it again.
|
||||
</div>
|
||||
|
||||
## Switching Modes
|
||||
## Entity Filter
|
||||
|
||||
When the dialog has already been launched, you can switch to other modes without losing your filter text.
|
||||
*Hotkey: `e`*
|
||||
|
||||
<p class='img'>
|
||||
<img src='/images/docs/quick-bar/quick-bar-switch-modes.gif' alt='Quick Bar'>
|
||||
Switch modes without losing filter text
|
||||
</p>
|
||||
|
||||
| Current Mode | Action | Switches to Mode |
|
||||
| ------------- | ------------- | ------------- |
|
||||
| Entity Filter | Use [hotkey](#hotkeys) (or prepend ">" to input field) | Command
|
||||
| Command | Use [hotkey](#hotkeys) (or remove ">" from input field) | Entity Filter
|
||||
|
||||
## Entity Filter Mode
|
||||
|
||||
*Hotkey: Ctrl+P (Windows) or ⌘+P (macOS)*
|
||||
|
||||
Similar to Developer Tools -> States view, but more lightweight and accessible from anywhere in the frontend.
|
||||
Similar to Configuration -> Entities, but more lightweight and accessible from anywhere in the frontend.
|
||||
|
||||
<p class='img'>
|
||||
<img src='/images/docs/quick-bar/quick-bar-entity-filter.gif' alt='Quick Bar'>
|
||||
Filter for entities in Quick Bar's entity filter mode
|
||||
</p>
|
||||
|
||||
Once launched, start typing your entity id (or ["bits and pieces" of your entity id](#search-by-bits-and-pieces-rather-than-complete-substring)) to get back a filtered list of entities. Clicking on an entity will open the "More Info" dialog for that entity.
|
||||
Once launched, start typing your entity id (or ["bits and pieces" of your entity id](#search-by-bits-and-pieces-rather-than-complete-substring)) to get back a filtered list of entities. Clicking on an entity (or hitting `enter` when the desired entity is highlighted) will open the "More Info" dialog for that entity.
|
||||
|
||||
This is helpful when, say, you are in the middle of writing an automation and need some quick insight about an entity but don't want to navigate away to Developer Tools.
|
||||
|
||||
## Command Mode
|
||||
## Command Palette
|
||||
|
||||
*Hotkey: Ctrl+Shift+P (Windows) or ⌘+Shift+P (macOS)*
|
||||
*Hotkey: `c`*
|
||||
|
||||
Run various commands from anywhere without navigating to another view.
|
||||
Run various commands from anywhere without having to navigate to another view.
|
||||
|
||||
<p class='img'>
|
||||
<img src='/images/docs/quick-bar/quick-bar-command-mode.gif' alt='Quick Bar'>
|
||||
Run commands in Quick Bar's "command mode"
|
||||
Run commands in Quick Bar's "command palette"
|
||||
</p>
|
||||
|
||||
Currently-supported commands:
|
||||
### Currently-supported commands
|
||||
|
||||
| Command | Action | Examples
|
||||
| ------------- | ------------- | ------------- |
|
||||
| "Reload {domain}" | Calls `{domain}.reload` | <ul><li>"Reload Scripts" calls `script.reload`</li><li>"Reload Scenes" calls `scene.reload`</li><li>etc...</li></ul> |
|
||||
Type | Available |
|
||||
| ------------- | ------------- |
|
||||
| Reload | All currently-supported "Reload {domain}" services.<br />*(E.g., "Reload Scripts")* |
|
||||
| Server | Restart/Stop |
|
||||
|
||||
## Disabling Shortcuts
|
||||
|
||||
You can enable or disable all of Home Assistant's keyboard shortcuts by going to your User Profile and clicking the "Keyboard Shortcuts" toggle button.
|
||||
|
||||
<p class='img'>
|
||||
<img src='/images/docs/quick-bar/disable-shortcuts-toggle.png' alt='Toggle for enabling or disabling keyboard shortcuts'>
|
||||
Toggle button for enabling/disabling keyboard shortcuts added by Home Assistant.
|
||||
</p>
|
||||
|
||||
## Tips
|
||||
|
||||
### Search by "bits and pieces" rather than complete substring
|
||||
### Search by "bits and pieces" rather than an exact substring
|
||||
|
||||
In Developer Tools -> States, if you're trying to find "light.chandelier" you would have to type out a complete, exact substring to match it (e.g., "light.cha" or "chandel").
|
||||
We know something like "**light.ch**" should match "**light.ch**andelier". Similarly, "**telev**" should match "media_player.**telev**ision".
|
||||
|
||||
But the Quick Bar checks *each letter* of your filter, finding entities that contain those letters, _in that order_. So, you can instead use "bits and pieces" of the entity id to narrow down matches more quickly (e.g., "ligcha", "ltlier", or "ltcdl").
|
||||
But with Quick Bar, "**lich**" would also match "**li**ght.**ch**andelier", and "**plyrtv**" would also match "media_**pl**a**y**e**r**.**t**ele**v**ision". It checks letter *sequences* rather than exact substrings.
|
||||
|
||||
This is similar to many modern developer-based applications like Sublime, VSCode, Chrome Developer Tools and GitHub file search do "quick file filter" searches.
|
||||
One nice use-case for this is that you can quickly filter out an entire domain of entities with just a couple letters and a period. For example, "**li.**" will match any "**light.***" entities. Continuing with "li.ch" would bring up the chandelier right away.
|
||||
|
||||
This can be really helpful when you have LOTS of entities with the same substring (e.g., "\*.living_room_\*"), but you only care about a particular _domain_. For example, rather than type out "media_player.living_" to narrow down media players in your living room, you can just type, say, "med.livroom" and get back the same set with less typing.
|
||||
### Filters work against friendly name too
|
||||
|
||||
If "light.hue_ceiling_light" has been named "Chandelier", you can type either "hue_ceil" or "chand" to find it.
|
||||
|
||||
### Use the enter key any time to open the top result in the list
|
||||
|
||||
As soon as the item you wanted shows up at the top of your filtered results, just hit "enter" to activate it -- no need to arrow down to the item, or click with your mouse.
|
||||
|
||||
### Use arrow keys to move around the list
|
||||
|
||||
When in the text field, use the down arrow `↓` to navigate down the item list. Hit `enter` to activate the currently-highlighted row.
|
||||
|
||||
When in the item list, use the up arrow `↑` to navigate up the item list, and to get back into the text field.
|
||||
|
||||
### Typing more letters will always add to your filter string
|
||||
|
||||
Say you've just used arrow keys to navigate half-way down the list, and want to add more text to your filter. You don't need to click back into the text field, just start typing new letters and they'll append to your filter.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Dialog doesn't launch using hotkeys
|
||||
|
||||
There are a few possible reasons why the quick bar dialog won't launch:
|
||||
|
||||
1. Your user is not an admin.
|
||||
2. The application lost focus. Try clicking into the main content area of the application and typing the shortcut again.
|
||||
3. You have disabled Keyboard Shortcuts in your User Profile settings.
|
||||
4. Shortcut is marked by browser as non-overridable. Firefox does this with some shortcuts, for example. But this shouldn't be a problem with single-key shortcuts currently used by the Quick Bar.
|
||||
5. Some other application or browser extension is using or overriding the shortcut. Try disabling the extension.
|
||||
|
||||
### A command is missing
|
||||
|
||||
The command list only shows commands that are available to you based on your user settings, and loaded integrations.
|
||||
|
||||
For example, if you don't have `automations:` in your config, then you won't see the "Reload Automations" command.
|
||||
|
||||
If "Advanced Mode" is turned off in User Settings, then any command related to advanced mode will not appear in the list.
|
||||
|
||||
If a command is missing that you feel is in error, please create an issue on GitHub.
|
||||
|
||||
### Shortcuts interfere with accessibility tools, browser extensions, or are otherwise annoying
|
||||
|
||||
You can [disable shortcuts](#disabling-shortcuts) in your User settings.
|
||||
|
||||
Please consider submitting an issue explaining why the shortcut was disruptive to you. Keyboard shortcuts are new to Home Assistant, and getting them right is a challenge for any Web application. We rely on user feedback to ensure the experience is minimally-disruptive.
|
||||
|
BIN
source/images/docs/quick-bar/disable-shortcuts-toggle.png
Normal file
BIN
source/images/docs/quick-bar/disable-shortcuts-toggle.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 76 KiB |
Binary file not shown.
Before Width: | Height: | Size: 4.8 MiB After Width: | Height: | Size: 9.7 MiB |
Binary file not shown.
Before Width: | Height: | Size: 137 KiB |
Loading…
x
Reference in New Issue
Block a user