# Keyboard shortcuts

Source: https://api-genie.dev/docs/reference/doc-components/keyboard-shortcuts
Part of the reference of [@mykulyak/apigenie-docs](https://api-genie.dev/docs/reference/doc-components.md).
Its other pages: [apg-api-reference and apg-spec](https://api-genie.dev/docs/reference/doc-components/reference-and-spec.md), [OpenAPI elements](https://api-genie.dev/docs/reference/doc-components/openapi.md), [Swagger 2.0 elements](https://api-genie.dev/docs/reference/doc-components/swagger.md), [AsyncAPI elements](https://api-genie.dev/docs/reference/doc-components/asyncapi.md), [Protobuf and gRPC elements](https://api-genie.dev/docs/reference/doc-components/protobuf.md), [GraphQL elements](https://api-genie.dev/docs/reference/doc-components/graphql.md), [Building blocks](https://api-genie.dev/docs/reference/doc-components/building-blocks.md), [Try it out](https://api-genie.dev/docs/reference/doc-components/try-it-out.md), [Theming](https://api-genie.dev/docs/reference/doc-components/theming.md), [Plugins](https://api-genie.dev/docs/reference/doc-components/plugins.md), [Server-side rendering](https://api-genie.dev/docs/reference/doc-components/server-side-rendering.md), [apigenie-docs build](https://api-genie.dev/docs/reference/doc-components/docs-build.md).

Since 0.2.0, `<apg-api-reference>` answers these keys anywhere on its page:

| Key | What it does |
| --- | --- |
| `/`, or Ctrl+K (Ctrl+K or Cmd+K on a Mac) | Puts the focus in the search box of the navigation. On a narrow screen it opens the sidebar first. |
| `J` | Shows the next page of the navigation. With `layout="single"`, scrolls to the next section. |
| `K` | Shows the previous page, or scrolls to the previous section. |
| `?` | Lists these shortcuts in a dialog. `?` again, Escape or *Close* closes it. |

On a layout that types no Latin letters, such as Cyrillic, Hebrew or Arabic, `J`, `K` and the
search key work by the key's place on the keyboard. On other layouts they follow the letter typed.

Try it out has keys of its own, inside its form: Ctrl+Enter (Cmd+Enter on a Mac) sends the
request.

A schema's rows take the arrow keys of a treegrid once one of them has the focus: Up and Down
between the rows, Right and Left to open and close a row and to move between its cells, Home and End
to the first and the last. The schema's section of the OpenAPI reference lists them.

## When a key does nothing

A shortcut does nothing in these cases:

- `/`, `J`, `K` and `?` do nothing while the reader types in a field, such as the search box or a
  parameter of Try it out. Ctrl+K and Cmd+K work from a field too.
- A key your page has already handled, by calling `preventDefault()` on the `keydown` event, is
  left alone. A listener of your page runs first when it is on `document`, on an element, or on
  `window` and added before the reference.
- A key with nothing to do keeps its usual effect. With `layout="single"` there is no sidebar to
  search, so `/` opens Firefox's quick find as on any page.
- While the `?` dialog is open, the other shortcuts do nothing.

## Paging with J and K

`J` and `K` follow the links the sidebar shows, in its order. For an OpenAPI document: the
introduction, the changelog, each tag's page followed by its operations, the webhooks, then the
schemas. A closed group without a page of its own, such as Schemas with more than 30 schemas, is
skipped until it is opened. In a document with more than 150 operations, the navigation closes
the groups of other tags. `J` past the last operation of a tag shows the next tag's page, which
opens its group. For AsyncAPI, Protobuf and GraphQL, they follow that standard's groups in the
same way. After a search, they follow its results.

A step is a link followed: it emits the cancelable `apg-navigate` event, and cancelling it lets
your application route, as for a click.

## Turning them off or changing Ctrl+K

```html
<apg-api-reference spec-url="/openapi.yaml" search-key="e"></apg-api-reference>
<apg-api-reference spec-url="/openapi.yaml" no-shortcuts></apg-api-reference>
```

- `search-key` names the letter that searches with Ctrl or Cmd, `k` by default. Pick another when
  your page uses Ctrl+K for its own search. It takes one letter from a to z. Any other value is
  reported as an `apg-config-error`, and Ctrl+K searches. `/` searches whatever the letter.
  Letters the browser keeps, such as `t`, `n` and `w`, do not reach the page.
- `no-shortcuts` turns off `/`, the search key, `J`, `K` and `?`. Try it out keeps Ctrl+Enter.
- Both can come from the config file (`config-url`), but not from the query string.
- With two references on one page, the one added to the page first answers the keys. Another
  answers only a key the first has nothing to do for. Give `no-shortcuts` to every reference but
  the one that should answer.

A server-rendered reference answers the keys once it is hydrated.

The [API Genie editor](/docs/reference/editor/keyboard-shortcuts) has shortcuts of its own, which
depend on where it runs.
