Keyboard & focus

Using a page with only the keyboard

Many people use a page with only the keyboard. Some can't use a mouse. Others just find the keyboard faster. A keyboard user can't click on things. Instead, they press Tab to move from one control to the next. A control is anything you can use on a page, like a button, a link, or a text box.

The control that is ready for the keyboard right now has focus. Only one element has focus at a time. When you press a key, the browser sends a key event to that element. So this lesson is about two things that work together:

• Key events tell you which key was pressed.
• Focus tells you which element gets those key events.

If people can't reach a control, open it, close it, and understand it with only the keyboard, they can't use it. In this lesson you'll try a key inspector, a shortcut, a focus log, a dialog that keeps focus inside, and a message that is read aloud.

When you press a key, the browser fires two events:

• keydown fires when the key goes down.
• keyup fires when the key comes back up.

If you hold a key down, most browsers fire keydown again and again. Each extra event is a repeat. On a repeat, event.repeat is true. The keyup event fires only once, when you let go.

There is also an old event called keypress. It is deprecated: browsers keep it only for old code, and new code should not use it. To know when the text in a field changes, listen for the input event instead. It fires for every way text can change:

• typing on a keyboard
• pasting
• autocomplete, when the browser fills in a saved value
• phone keyboards and speech
• an input method editor (IME): a tool that builds one character from several key presses, used for languages like Chinese and Japanese

const event = { key: "Enter", repeat: false };
console.log(event.key);
console.log(event.repeat);

This code uses a plain object that looks like a key event, so it can run anywhere. Line 1 makes the object. Line 2 prints the name of the key, Enter. Line 3 prints false, because this is the first event, not a repeat.

const field = { value: "Asha" };
field.value = "Asha Patel";
console.log(field.value);

Line 1 makes an object that stands for a text field holding Asha. Line 2 changes the whole value at once. Line 3 prints Asha Patel. A real input event tells you the new value in the same way. It doesn't matter if the text came from one key, a paste, autocomplete, speech, or an IME.

1box.addEventListener("keydown", (event) => {2  if (event.key === " " || event.key === "ArrowDown") event.preventDefault();3  show({4    key: event.key,5    code: event.code,6    repeat: event.repeat,7    shiftKey: event.shiftKey,8    ctrlKey: event.ctrlKey,9    altKey: event.altKey,10    metaKey: event.metaKey,11    capsLock: event.getModifierState("CapsLock"),12    isComposing: event.isComposing,13  });14});15 16box.addEventListener("keyup", showRelease);17// `keypress` is deprecated; use `input` for text and `keydown`/`keyup` for keys.

Look at the modifier flags in the log. A modifier is a key you hold while you press another key:

• shiftKey is true while Shift is held.
• ctrlKey is true while Ctrl is held.
• altKey is true while Alt is held. On a Mac, this key is called Option.
• metaKey is true while Command is held on a Mac.

Caps Lock works differently, because it stays on after you let go. To check it, call event.getModifierState("CapsLock"). While someone is building a character with an IME, event.isComposing is true. Shortcut code should ignore those key presses, because the person is still typing. A command that should run only once should also ignore events where event.repeat is true.

Every key event has two names for the key:

• event.key is what the key types right now, with the person's keyboard layout. Examples: "a", "A", "Enter", "ArrowLeft", and " " (one space) for the Space bar.
• event.code is where the key sits on the keyboard, no matter what it types. Examples: "KeyA", "Digit1", "Space", and "ShiftLeft".

A keyboard layout is which letter goes on which key. It is different in different countries. On a French keyboard, the key where a US keyboard has Q types the letter a. So for that key, event.key is "a", but event.code is still "KeyQ".

Some layouts have dead keys. A dead key adds an accent to the next letter: press the accent key, then e, and you get é. When you press the dead key itself, event.key is "Dead", because nothing is typed yet.

1const target = "page";Run2const event = { key: "k", metaKey: true, ctrlKey: false, repeat: false, isComposing: false };3const editingText = target === "input";4const commandKey = event.metaKey || event.ctrlKey;5const opensPalette = commandKey && event.key.toLowerCase() === "k" && !editingText && !event.repeat && !event.isComposing;6console.log(opensPalette ? "open palette" : "let the browser type");

A shortcut is a key combination that runs a command, like Ctrl+K to open a search box. A good shortcut listens only inside the part of the page that owns it. The demo below opens a command palette: a small box where you type a command. It follows three rules:

• It listens only inside its own demo area.
• It accepts Command+K on a Mac and Ctrl+K everywhere else.
• It calls preventDefault() only for that exact shortcut. preventDefault() stops the browser's own action for the key, so every other key keeps working as normal.

1demo.addEventListener("keydown", (event) => {2  const editing = event.target.matches("input, textarea, [contenteditable]");3  const command = event.metaKey || event.ctrlKey;4  if (command && event.key.toLowerCase() === "k" && !editing && !event.repeat && !event.isComposing) {5    event.preventDefault();6    openPalette();7  }8});

Focus is more than the ring you see around a control. It decides where key presses go. Some elements can get focus on their own: links, buttons, text fields, select menus, and text areas. Any other element needs the tabindex attribute:

• tabindex="0" puts the element in the normal Tab order, in the order it appears on the page.
• tabindex="-1" lets your code focus the element, but Tab skips it.
• A positive number, like tabindex="3", makes Tab visit the element before the normal order. Avoid it, because the order becomes hard to predict.

When focus moves, the browser fires four events: focus, blur, focusin, and focusout. Only two of them bubble. Bubbling means the event also reaches the parent elements, so one listener on a container hears every child.

Each row is one focus event. Read across to see if it bubbles, and what it is good for.

1container.addEventListener("focus", log, true);2container.addEventListener("blur", log, true);3container.addEventListener("focusin", log);4container.addEventListener("focusout", log);5 6laterButton.focus({ preventScroll: true });7console.log(document.activeElement);

document.activeElement is the element that has focus right now. Check it after the focus move is done. Each focus event also has a relatedTarget: the other element in the move.

• For focus and focusin, it is the element that just lost focus.
• For blur and focusout, it is the element that gets focus next.
• It is null when focus comes from, or goes to, somewhere outside the page.

To move focus with code, call element.focus(). If the jump would scroll the page and confuse people, write element.focus({ preventScroll: true }) instead.

const tabOrder = { customBox: 0, dialogTitle: -1 };
console.log(tabOrder.customBox);
console.log(tabOrder.dialogTitle);

This is a plain object, not the real page. Line 2 prints 0: a custom box that belongs in the normal Tab order. Line 3 prints -1: a dialog title that code can focus, but Tab skips.

Make focus easy to see. The CSS selector :focus-visible matches a focused element when the browser thinks a ring helps, mostly when someone uses the keyboard. So you can show a strong ring for keyboard users without showing it on every mouse click.

A modal dialog is a box that opens on top of the page. The page behind it can't be used until the dialog closes. While the dialog is open, three things should be true:

• Tab and Shift+Tab move only between the controls inside the dialog. This is called a focus trap.
• Escape closes the dialog, unless there is a good reason not to.
• When the dialog closes, focus goes back to the button that opened it.

Without these, a keyboard user can Tab to controls hidden behind the dialog, or lose their place on the page.

const items = ["Home", "Settings", "Help"];
let index = 0;
function move(direction) {
  index = (index + direction + items.length) % items.length;
  return items[index];
}
console.log(move(1));
console.log(move(-1));

The same wrap-around idea works for any list, so start with a simple one. Line 1 makes a list of three names. Line 2 starts at index 0, Home. On line 4, move adds the direction (1 or -1) to the index. The % sign gives the remainder after dividing by the list length. That makes the index wrap: going past the end lands on the start. Adding items.length first keeps the number from going below 0, so going before the start lands on the end.

Line 7 moves down and prints Settings. Line 8 moves back up and prints Home. A real list or menu also needs a clear style for the current item and a name for screen readers. This code only moves the index.

1const focusables = [...dialog.querySelectorAll("button, input, [href]")];2dialog.addEventListener("keydown", (event) => {3  if (event.key === "Escape") closeDialog();4  if (event.key !== "Tab") return;5  const first = focusables[0];6  const last = focusables.at(-1);7  if (event.shiftKey && document.activeElement === first) {8    event.preventDefault();9    last.focus();10  } else if (!event.shiftKey && document.activeElement === last) {11    event.preventDefault();12    first.focus();13  }14});

There are two ways to build a modal dialog. Each row shows what you get, and what you still have to do yourself.

1const focusables = ["open", "cancel", "save"];2let activeIndex = 0;3function moveFocus(direction) {4  activeIndex = (activeIndex + direction + focusables.length) % focusables.length;5  return focusables[activeIndex];6}7console.log(moveFocus(1));8console.log(moveFocus(-1));

This list holds three controls, and focus starts on open. Line 7 moves forward and prints cancel. Line 8 moves back and prints open. A real trap uses the same wrap for Tab and Shift+Tab.

ARIA attributes are extra attributes that describe the page to screen readers. They only describe things. They don't add any behavior.

A disclosure is a button that shows or hides a panel, like a Filters button. Give the button two attributes:

• aria-expanded says if the panel is open: "true" or "false".
• aria-controls holds the panel's id, so screen readers know which panel the button opens.

The button still needs real button behavior. ARIA doesn't add a click handler or a key handler for you.

A live region is an element that a screen reader reads aloud whenever its text changes. Focus doesn't move to it. You make one with the aria-live attribute, or with a role such as role="status".

const button = { "aria-expanded": "false" };
button["aria-expanded"] = "true";
console.log(button["aria-expanded"]);

Line 1 makes an object that stands for the button, with aria-expanded set to "false". Line 2 changes it to "true", and line 3 prints true. On a real page, your click handler must also show or hide the panel. The attribute only describes it.

1button.setAttribute("aria-expanded", String(open));2button.setAttribute("aria-controls", "filter-panel");3panel.hidden = !open;4 5status.textContent = `3 results found`;6// The live region existed before this text changed.

Put the live region on the page first, and change its text later. If the region and its text appear at the same moment, screen readers may miss the text. Use polite for normal updates, like "3 results found". Use assertive or role="alert" only for urgent messages, because they interrupt whatever the screen reader is saying.

Where you'll use keyboard and focus code

Keyboard and focus code shows up in most real websites:

• search boxes that search when you press Enter
• menus that close when you press Escape
• command palettes that open with Ctrl+K or Command+K
• skip links: a link at the top that jumps past the menu to the main content
• a list of form errors that gets focus after a failed submit
• panels that open and close, and lists that suggest words as you type
• modal dialogs

Here is the shortcut check from the step-through again, as one block of code:

1const target = "page";2const event = { key: "k", metaKey: true, ctrlKey: false, repeat: false, isComposing: false };3const editingText = target === "input";4const commandKey = event.metaKey || event.ctrlKey;5const opensPalette = commandKey && event.key.toLowerCase() === "k" && !editingText && !event.repeat && !event.isComposing;6console.log(opensPalette ? "open palette" : "let the browser type");

Line 3 checks if focus is in a text field. Line 4 accepts Command or Ctrl. Line 5 opens the palette only for K, only outside a text field, and not for a repeat or IME typing. Focus is on the page here, so line 6 prints open palette.

Four rules to remember:

• Use keydown for commands. Use input to check text.
• Check where focus is before you take over a key.
• Call preventDefault() only for the exact keys you own.
• When a dialog or menu closes, send focus back to where it was.

Common mistakes

• "keypress is the event for text." keypress is deprecated. Use input to know when text changes.
• "key and code are the same." key is what the key types with the current layout. code is where the key sits.
• "A div with a click handler is a button." A real button already gets focus, works with Enter and Space, can be disabled, and tells screen readers it is a button.
• "focus and blur bubble." They don't. Use a capture listener, or use focusin and focusout, which do bubble.
• "A dialog is done once it looks right." It also has to keep focus inside, make the page behind it inert, have a name, close on Escape, and send focus back.
• "A live region always works the same way." Screen readers differ, so test your live regions with real screen readers.

Key takeaways

• keydown fires when a key goes down, and repeats while you hold it. Use it for commands. keyup fires once, when you let go.
• key is what the key types. code is where the key sits on the keyboard.
• Use the input event for text changes. It also covers pasting, IME typing, phone keyboards, and autocorrect.
• focus and blur don't bubble. focusin and focusout do.
• A modal dialog keeps focus inside, closes on Escape, makes the page behind it inert, and sends focus back when it closes.
• aria-expanded says if a panel is open. A live region reads out new text without moving focus.

Up next: Page & resource loading.