Keyboard shortcuts

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

<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 has shortcuts of its own, which depend on where it runs.

Last updated on View as Markdown
Was this helpful?