Event Listeners and Interactive Web Pages

A page can wait for a person to act. An event reports something that happened, and an event listener is the function called in response. Registering a listener sets up that response; it does not perform the action immediately.

Add the function to the element

Select an element that already exists, choose the event's exact name, and pass a function:

const button = document.querySelector("#like");
let likes = 0;
button.addEventListener("click", function () {
  likes = likes + 1;
  button.textContent = "Likes: " + likes;
});

The selection, variable setup, and registration run when the script runs. Each later click runs the function body. After three clicks the button displays "Likes: 3". Keeping likes outside the function preserves the total between clicks; putting let likes = 0 inside would restart it each time.

Pass a function reference, such as showMenu, without parentheses. In button.addEventListener("click", showMenu()), JavaScript calls showMenu immediately and passes its return value as the listener. To supply an argument later, wrap the call: button.addEventListener("click", () => showMenu("main"));.

Choose an event that actually occurs

Names are case-sensitive strings without an "on" prefix. Use "click", not "Click" or "onclick". A made-up name is accepted without an error, but the browser will not emit it for a click. Common families include pointer events such as pointerdown and pointerup, keyboard events such as keydown, form events such as input and submit, and focus events such as focusin. DOMContentLoaded has its own exact capitalization.

Set up the right element at the right time

A script in the head can run before a button exists. Selection then returns null, and calling addEventListener on it throws an error. Load an external script with defer, place it after the markup, or register setup on the document's DOMContentLoaded event. An element created later needs setup after creation or a listener on an ancestor.

querySelectorAll returns a NodeList, not one event target. Register on its elements:

document.querySelectorAll(".tab").forEach((tab) => {
  tab.addEventListener("click", selectTab);
});

Let listeners coexist

Listeners with the same capture setting run in registration order. At the event target, capture listeners run before non-capture listeners. Adding the same function object again with the same type and capture setting does not add a second copy.

The browser passes an event object to your listener. Its properties explain the event that triggered this particular call. Name the parameter event or e; the parameter name is your choice.

button.addEventListener("click", (event) => {
  console.log(event.type);
  console.log(event.currentTarget);
});

This logs "click" and the button during the listener call. Logging the whole object can help you discover its other properties.

Separate the origin from the listener

Imagine a button containing an image:

<button id="save" data-id="7">
  <img src="disk.svg" alt=""> Save
</button>

Clicking the text "Save" makes the button the target too. The text is part of the button; it does not turn into a separate element target.

This difference matters when reading data. The image does not have the button's data-id, so event.target.dataset.id is undefined on an image click. A listener attached directly to the button can read event.currentTarget.dataset.id. A listener on a larger container can find the intended button with event.target.closest("button") and check that a match exists.

Read the details for this event

Every event has a type, a target, and a currentTarget. The Boolean bubbles says whether it travels back up through ancestors. cancelable says whether code may cancel its default action, and defaultPrevented records whether that cancellation has happened. timeStamp records the event's creation time in milliseconds relative to the page's time origin.

Different event families add useful details. A modern click supplies a PointerEvent, which inherits mouse-event properties such as clientX, clientY, and button. A KeyboardEvent adds key, code, and modifier flags. An input listener can use event.target.value to read the field's new text.

For a gallery listener, event.target.tagName might be "IMG" when a photo is clicked or "DIV" when the gap is clicked. Handle the case actually reported. Do not assume every event inside a container came from the same kind of child.

Use the value while the listener runs

In a regular function listener, this equals event.currentTarget. An arrow function takes this from its surrounding code; it does not acquire the element as this. Using event.currentTarget works with either function style.

After dispatch, currentTarget is reset to null. A console may show that later value when you expand a previously logged event. Log event.currentTarget directly inside the listener to inspect the element during the call.

A listener should stay active for as long as its feature needs it. For a temporary keyboard interaction, keep the function reference so it can be removed when the interaction closes.

Remove the same function

function onKey(event) {
  console.log(event.key);
}
document.addEventListener("keydown", onKey);
// When the feature closes:
document.removeEventListener("keydown", onKey);

Removal matches the event type, function object, and capture setting. An anonymous function can also be removed when its reference is saved, as in const handler = () => save();. Writing a fresh () => save() in the removal call creates a different function, even though the code looks identical.

Choose the registration options

A one-time welcome banner can use { once: true }. A feature with several listeners can give them one signal:

const controller = new AbortController();
window.addEventListener("pointermove", moveCursor, {
  signal: controller.signal
});
window.addEventListener("keydown", onKey, {
  signal: controller.signal
});
// Close the feature:
controller.abort();

Aborting removes both registrations. An aborted controller cannot be reset; create a new controller for a new lifetime. For removal by removeEventListener, repeat capture: true if it was used on registration. once, signal, and passive do not form part of the removal match.

A passive listener's preventDefault() call is ignored. Browsers commonly default certain scrolling-related listeners on document-level targets to passive, including wheel, touchstart, and touchmove; explicitly use { passive: false } there when cancellation is needed.

Avoid accumulating callbacks

If each "Start" click adds a fresh anonymous board listener, starting twice makes one board click run two callbacks. Install the board listener once, reuse the same function object, or abort the previous group before replacing it. Distinct once callbacks can still accumulate before they fire.

Detaching an element preserves its listeners. They work if it is reinserted, and dispatchEvent() can reach them while it is detached. The element becomes eligible for garbage collection when it and its listeners are unreachable. A listener on window or document remains attached until explicitly removed.

Send a custom event

const event = new CustomEvent("cart:add", {
  detail: { id: 42 },
  bubbles: true
});
item.dispatchEvent(event);

Listeners read event.detail.id. Dispatch calls the listeners immediately, before returning. bubbles: true lets ancestors hear it too. An event sent with dispatchEvent() has isTrusted equal to false; browser-dispatched events can be trusted even when an API such as focus() caused them.

A click inside a button can also be heard by the button's ancestors. Propagation is the event's journey through the document tree. Following that journey explains both useful shared listeners and surprising extra actions.

Follow three phases

1. Capture: the event travels from window down through the ancestors toward the target.
2. Target: listeners run at the element where the event began.
3. Bubble: a bubbling event travels back up through the ancestors to window.

The eventPhase property reports 1 for capture, 2 at the target, and 3 for bubbling. A listener registered without options runs at the target or on the bubbling path. A listener with { capture: true } runs on the downward path, including at the target if registered there.

Trace a concrete click

<div id="outer">
  <div id="inner">
    <button>Go</button>
  </div>
</div>

Suppose the button and each div have ordinary click listeners that log their names. Clicking "Go" logs "button", "inner", then "outer". Clicking an empty area of inner logs "inner", then "outer"; the button is not on that event's path.

Now add a capture listener to outer. A button click logs "outer (capture)" first, then "button", "inner", and "outer" from the ordinary listeners. The capture listener sees the click before the descendants do. After outer, the event can continue through body, html, document, and window if listeners are registered there.

It is one event, not a new click created at every ancestor. target remains the button throughout. currentTarget changes as each listener runs. In the outer listener, reading target still identifies the original button.

Check which events bubble

The event's bubbles property tells you whether it has a bubbling phase. Non-bubbling events can still be observed by an ancestor's capture listener. To handle focus changes through an ordinary container listener, choose focusin or focusout.

Explain a nested-action bug

A product card opens a detail view when clicked. Its "Remove" button deletes the product. Clicking that button first deletes it, then reaches the card listener and opens the detail view. The event path explains why both callbacks run.

The card can ignore removal clicks with if (event.target.closest(".remove")) return;. Alternatively, the button can stop propagation. Filtering at the card preserves the event for other ancestors that may need it.

A listener can change what happens after an event, or where the event travels. These are separate decisions. A link may keep bubbling even after navigation has been canceled.

Replace a browser action

A default action is behavior the browser supplies: following a link, submitting a form, toggling a checkbox, inserting text, scrolling with Space, or moving focus with Tab. Use preventDefault() when your code replaces that action:

help.addEventListener("click", (event) => {
  event.preventDefault();
  openHelpPanel();
});

For a link to /help, this opens the panel without navigating. The link still offers its destination when JavaScript does not run.

Only cancelable events support cancellation. Inspect event.cancelable; defaultPrevented records successful cancellation. input occurs after the value changes and is not cancelable. Calling preventDefault() there does not remove the inserted text. A cancelable beforeinput event is the appropriate place to intercept an edit; canceling a relevant keydown can prevent that key's default effect.

Control propagation separately

A link whose listener only stops propagation still follows its URL. Canceling navigation alone still lets a document click listener hear the event. Returning false from an addEventListener callback does neither. A handler property or inline handler can cancel its default by returning false, but that still does not stop propagation.

Keep shared behavior working

An ancestor may close a menu or count interactions. Stopping propagation hides the event from that code. Often the ancestor can inspect target or defaultPrevented instead.

For example, a menu closes only when a click falls outside both the menu and its opener:

document.addEventListener("click", (event) => {
  if (!menu.contains(event.target) &&
      !menuButton.contains(event.target)) {
    menu.hidden = true;
  }
});

contains() includes the element itself and its descendants. Checking the opener matters because its opening click also bubbles to the document. Without that second test, the newly opened menu would close immediately.

Cancel only a handled action

In a key listener, check the key before canceling. Canceling every key blocks ordinary typing and can prevent Tab from moving focus. In a passive listener, cancellation is ignored altogether.

Event delegation places a listener on a stable ancestor and uses the event's origin to choose an action. It is useful when a list has many items or when code creates new items after setup.

Find the intended control

A bubbling click reaches the list no matter which of its descendants was clicked. Start at event.target, find the nearest matching control, and reject unrelated clicks:

const list = document.querySelector("#todos");
list.addEventListener("click", (event) => {
  const button = event.target.closest(".remove");
  if (!button || !list.contains(button)) return;
  const item = button.closest("li");
  console.log("Removing item " + item.dataset.id);
  item.remove();
});

The list contains items such as <li data-id="7">Buy milk <button class="remove">Remove</button></li>. The listener belongs to the list, so a new item with the same markup works immediately after insertion.

Trace an icon click through the code. The target is the icon, closest(".remove") finds its button, and button.closest("li") finds the item. Its data-id identifies the item in the message. Finally, remove() changes the page.

Keep the two guards

Testing only event.target.matches(".remove") loses icon clicks because the icon itself does not match. closest() checks the target and walks up its ancestors. In a delegated listener, currentTarget is the list; it does not become the matched button.

Route several actions

Data attributes let one toolbar listener choose among known actions:

const actions = { bold: makeBold, italic: makeItalic,
  clear: clearText };
toolbar.addEventListener("click", (event) => {
  const button = event.target.closest("button[data-action]");
  if (!button || !toolbar.contains(button)) return;
  const action = actions[button.dataset.action];
  if (typeof action === "function") action();
});

A button with data-action="clear" selects clearText. The function check handles an unknown action without attempting to call undefined.

Choose a suitable event

Delegation works with bubbling events beyond clicks. A single form input listener can pass event.target to a field-checking function. To delegate focus changes, use focusin or focusout; ordinary focus and blur do not bubble. For hover transitions use bubbling over/out events when delegation is required.

A descendant's stopPropagation() can prevent an event from reaching the container. When a delegated listener seems inactive, check the event type, the target, the selector match, and whether something below the container stopped the journey.

Keyboard input goes to the focused element, available as document.activeElement, then bubbles. A document listener can therefore hear keys from fields as well as from other controls. That reach makes keyboard shortcuts useful, but it also means they can interrupt typing.

Choose the property by its meaning

On an AZERTY keyboard, the position labeled Q on a US keyboard produces key "a" and code "KeyQ". Use key for meaning, such as Escape to close or a letter shortcut. Use code for fixed positions, such as movement keys in a game. The space bar's key is a single space, not "Space".

keydown fires on the initial press and can repeat while held. Repeated calls have event.repeat === true. keyup fires on release. Use keydown instead of the deprecated keypress event.

Handle a shortcut precisely

document.addEventListener("keydown", (event) => {
  if ((event.ctrlKey || event.metaKey) &&
      event.key.toLowerCase() === "s") {
    event.preventDefault();
    saveDraft();
  }
});

This handles Ctrl+S and Command+S. Lowercasing allows "S" too. Cancellation replaces the browser's Save Page action only for the matching shortcut. Other modifier flags include shiftKey and altKey.

For a page-wide single-letter shortcut, skip typing contexts before acting:

if (event.target.matches("input, textarea, select") ||
    event.target.isContentEditable) return;
if (event.repeat) return;

The first guard protects text entry. The second makes an action run once per physical press. Do not cancel Tab across the page; it is how keyboard users move on.

Listen for text after it changes

For an ordinary printable key, the sequence is keydown, beforeinput, input, then keyup. Reading value in keydown gives the value before that character was inserted. Use input for a text preview or character count. It also handles edits such as paste and dictation that need no matching key press.

Observe focus changes

focus and blur report receiving and losing focus without bubbling. focusin and focusout bubble, so a form can observe its fields through one listener. relatedTarget identifies the other element in the change, or null when there is none.

password.addEventListener("focus", () => {
  hint.hidden = false;
});
password.addEventListener("blur", () => {
  hint.hidden = true;
});

The hint is available when the field receives focus, including through Tab. Calling element.focus() moves focus from code; the next keyboard input then goes to that element.

A person may use a mouse, a finger, a pen, or a keyboard. Choose an event by the interaction you need. click expresses activation; pointer events describe pressing, moving, and releasing.

Keep actions available through the keyboard

A native button emits click when activated with Enter or Space. A focused link does so with Enter. Wiring an action only to pointerdown or mousedown misses those keyboard activations. Use click for actions such as opening a panel; use pointerdown when work must begin at the press, such as dragging.

A pointer click follows a press and release. When they occur on different elements, the click can target their nearest shared ancestor. dblclick follows two quick clicks; event.detail counts quick successive clicks. auxclick handles non-primary clicks. contextmenu can come from a secondary click, a touch long press, or a keyboard menu command.

Use one pointer family

pointerdown, pointermove, pointerup, and pointercancel cover mouse, touch, and pen. pointerType identifies the device as "mouse", "touch", or "pen"; pointerId distinguishes active pointers, including two fingers.

Older mouse and touch event families still exist. Browsers may emit compatibility mouse events after pointer events. Registering both pointerdown and mousedown for the same action can therefore run it twice.

Match coordinates to the job

When the document is scrolled down 300 px and a click is 100 px below the viewport top, clientY is 100 and pageY is 400. Keep both positions in the same coordinate frame when calculating movement. A changing nested target can also change the origin of offset coordinates.

button reports which button changed on a down or up event: 0 primary, 1 middle, 2 secondary. buttons reports the currently held combination: primary contributes 1, secondary 2, and middle 4. Thus buttons === 3 means primary and secondary are held; it does not mean the middle button changed.

Choose hover behavior for a whole control

Over/out events bubble and can fire as the pointer crosses child boundaries. Enter/leave events do not bubble and describe entering or leaving the whole element, including its children. A tooltip can avoid child-boundary flicker with pointerenter and pointerleave.

Touch and keyboard users do not hover. Offer essential information on click or focus too. For a visual hover effect with no extra behavior, CSS :hover is simpler than a listener.

Dragging needs memory across several events. Store the pointer's starting coordinates and the element's starting position. Each move then applies the difference from that starting point, so the element does not jump to place its corner under the pointer.

Work out the displacement

A box starts at left: 100px; top: 50px. The pointer starts at viewport coordinates 220, 140 and moves to 260, 125. The horizontal change is 40 px; the vertical change is −15 px. Adding those changes to the box's starting position gives left: 140px; top: 35px.

Use consistent client coordinates for both pointer readings. The general calculation is element start plus pointer displacement. Do not add each full displacement to the box's already updated position, which would count earlier movement again.

Remember and capture one pointer

For a margin-free, absolutely positioned box inside a relatively positioned container:

let start = null;
box.addEventListener("pointerdown", (event) => {
  if (start || event.button !== 0) return;
  start = { id: event.pointerId, x: event.clientX,
    y: event.clientY, left: box.offsetLeft,
    top: box.offsetTop };
  box.setPointerCapture(event.pointerId);
});
box.addEventListener("pointermove", (event) => {
  if (!start || event.pointerId !== start.id) return;
  box.style.left = start.left +
    (event.clientX - start.x) + "px";
  box.style.top = start.top +
    (event.clientY - start.y) + "px";
});
function endDrag(event) {
  if (start && event.pointerId === start.id) start = null;
}
box.addEventListener("pointerup", endDrag);
box.addEventListener("pointercancel", endDrag);

The stored ID rejects movement and release from a second pointer. offsetLeft and offsetTop provide starting positions as numbers; styles need the "px" suffix.

Pointer capture keeps subsequent events for that pointer directed to the box even when it moves outside the box. The browser releases capture after pointer up or cancellation. releasePointerCapture(id) can release it earlier.

Handle the browser taking over

A touch gesture may become page scrolling or zooming, causing pointercancel. End the drag there as well as on pointerup; otherwise stale state can keep moving the box later. Apply touch-action: none to the drag surface before interaction to reserve its gesture. Keep it local so the rest of the page can scroll.

Use user-select: none on the draggable surface to avoid selecting text. Set draggable="false" on its images to prevent the native image-drag behavior.

Offer another way to move

Provide keyboard movement for a focused control and clickable or tappable move buttons. Arrow keys alone do not supply a single-pointer alternative to dragging. WCAG 2.2 SC 2.5.7 requires such an alternative unless dragging is essential or is unmodified browser behavior. Native move buttons can serve both keyboard and pointer users.

The separate HTML Drag and Drop API uses dragstart, dragover, and drop to transfer data, such as files. Its event sequence is different from this pointer-based position change.

Form controls expose different kinds of state. A text field's value is a string; a checkbox's checked is a Boolean. Reading the right property is the first step toward reliable calculations and previews.

Convert numbers deliberately

Even <input type="number"> has a string value. With the text "3", adding 1 gives "31". Number(input.value) + 1 gives 4. A number input also exposes valueAsNumber.

Empty input needs its own decision. Number("") gives 0, which can make a missing quantity look like a real zero. Check input.value === "" first, or use valueAsNumber, which gives NaN for an empty number field. Test that result with Number.isNaN().

Read the selected state

A checkbox's value is its configured submission text, or "on" if none is supplied. It does not tell you whether it is checked. A select reports the chosen option's value. To find a selected radio element itself, query input[name="size"]:checked.

Match the event to the update

input reports user edits as they happen, including typing and paste. change reports a committed choice: after a changed text field loses focus, or immediately when a checkbox, radio button, or select is changed.

message.addEventListener("input", () => {
  counter.textContent = 280 - message.value.length +
    " characters left";
});

After "Hello", five characters have been used and the counter reads "275 characters left". A keydown listener would run before the new character enters the value and would miss pasting through a menu. Assigning message.value from code does not fire either input or change; call the update function directly too.

Collect a form's named fields

form.elements.email.value accesses a control by name or ID. Use form.elements["first-name"] for a hyphenated name. Submission uses names: an ID alone does not put a field in the data.

const data = new FormData(form);
const email = data.get("email");
const topics = data.getAll("topics");

FormData collects the current eligible name/value pairs. Unchecked checkboxes, disabled controls, and nameless fields are omitted. get() returns the first value for a name; getAll() preserves repeated values, such as several checked topics. File controls can supply file objects; ordinary text controls supply strings.

Object.fromEntries(data) is convenient for distinct names, but keeps only the last pair for repeated names. Choose getAll() when each selection matters. Because input bubbles, one form listener can read event.target to update whichever field changed.

Submission belongs to the form. Listen for its submit event to handle a submit-button click, Enter in a single-line field, and a scripted requestSubmit() through one route.

Replace navigation with a page update

Normally a form sends data to its action URL and loads the response. Without an action, the destination is the current page. The default GET method places the data in the URL. To update the current page with JavaScript, cancel that default action:

const form = document.querySelector("#new-todo");
form.addEventListener("submit", (event) => {
  event.preventDefault();
  const data = new FormData(form);
  const title = data.get("title").trim();
  if (title === "") return;
  addTodo(title);
  form.reset();
});

This form has an enabled text field named title. The listener trims surrounding spaces, ignores an empty result, adds an item, and resets fields to their initial values. reset() does not always mean empty; a control with an initial value returns to that value.

If the item appears briefly and disappears as the page reloads, check whether preventDefault() is missing. A button click listener alone is the wrong boundary for form handling, especially when another route submits the form.

Know what triggers submission

Implicit submission from Enter can click the enabled default submit button. Enter in a textarea inserts a newline. A button inside a form defaults to a submit button when its type is omitted, so a "Show password" button should explicitly use type="button".

When there are multiple submit buttons, event.submitter identifies the one used. It can be null for routes without a specific button, so code should check before reading it:

const button = event.submitter;
const intent = button ? button.value : "save";
const data = button ? new FormData(form, button) :
  new FormData(form);

A named submitter such as name="intent" value="publish" contributes that pair when passed to FormData. A FormData(form) call by itself does not include a submit button's name/value pair.

Preserve the validation route

Built-in validation runs before the submit event. If an empty required field fails, the browser reports the problem and does not dispatch submit. A custom check only inside that listener will not run on this failed attempt. novalidate on the form disables the automatic validation step.

Use requestSubmit() when code needs the normal validation and submit-event path. It requests submission without dispatching a button click. Pass a particular submit button to requestSubmit(button) when that button's submission settings should apply.

HTML can describe many input rules without a custom JavaScript test. The browser checks those rules during submission and exposes the results for your code. Start with the constraints that match the data you need.

Choose a constraint

For pattern="[0-9]{5}", "12345" passes; "1234", "123456", and "12345a" fail. The pattern covers the whole value, not any matching substring. Empty input skips the pattern check, so add required when omission is not allowed.

Email validation checks syntax, not whether an inbox exists. Both "ann@example.com" and "ann@example" pass the browser's email rule, while "ann.example.com" does not. An additional pattern can impose a more specific format when the application requires it.

Read the reason for failure

A field's validity object contains Boolean flags. valueMissing, typeMismatch, patternMismatch, tooShort, and tooLong describe missing or malformed text. rangeUnderflow, rangeOverflow, and stepMismatch describe numeric constraints. badInput covers an input the browser cannot turn into a usable value, and customError records a custom validity message. valid is true when no constraint fails.

For a number field with min="0" max="10" step="2", 12 is above the maximum, 7 is off the allowed step, and 6 passes. More than one flag can be true; do not assume every invalid field has exactly one problem.

Check quietly or report visibly

checkValidity() returns a Boolean and fires invalid on failing controls without showing the browser's message. reportValidity() checks and also reports the problem to the user. Call either on a field or a form. validationMessage gives the message in the browser's language. The invalid event does not bubble.

Text-length constraints apply to user-entered text. Assigning input.value = "ab" in code does not make tooShort true just because minlength is 3. maxlength normally also prevents further user typing beyond its limit.

Show errors at a helpful time

:invalid applies immediately, so an untouched required field already matches. :user-invalid waits for user interaction or a submission attempt and can avoid an early red field. Use text to explain the error as well as a visual style.

novalidate skips automatic submission validation for the form; formnovalidate skips it for one submit button. They do not remove constraints or disable checkValidity(). Browser checks help users correct mistakes; the server must validate received data again because a request can bypass the page.

A rule involving two fields needs code. For example, a confirmation must match a password, or an end date must follow a start date. Keep the rule separate from how and when its error is displayed.

Set and clear a custom error

A nonempty string passed to setCustomValidity() marks the field invalid and sets customError. Passing "" clears that custom failure; required, pattern, or other constraints can still fail.

function checkMatch() {
  const matches = confirm.value === password.value;
  confirm.setCustomValidity(matches ? "" :
    "The passwords do not match.");
}
password.addEventListener("input", checkMatch);
confirm.addEventListener("input", checkMatch);

Recheck both dependencies. Changing the first password can break a previously correct confirmation. A message that is never cleared keeps the field invalid after the person fixes the mismatch. Run the initial check too when fields can start with values.

Date inputs provide ISO strings such as "2026-03-10", regardless of the displayed local date format. Nonempty values from these controls can be compared as text. If the rule says the end must be after the start, reject end.value <= start.value, including equality. Handle missing dates through required or a separate empty-value check.

Explain the next useful action

A message should identify the problem and its correction. For a missing email, say "Enter your email address." For malformed email text, say "Enter an email address in the form name@example.com." Keep the entered value so the person can edit it.

A required name field accepts spaces because they form a nonempty string. Check name.value.trim() === "" when surrounding whitespace should not count. Clear this custom error when meaningful text appears.

Connect messages to controls

<label for="email">Email</label>
<input id="email" name="email" type="email"
  required aria-describedby="email-error">
<p id="email-error"></p>

Place the error in that paragraph and set aria-invalid="true" while the field has an error. Clear the text and remove or set aria-invalid to "false" after correction. aria-describedby connects the explanation to the field for assistive technology. Use text; a red border alone cannot tell everyone what failed.

Choose the validation flow

For fully custom messages, add novalidate and use a form submit listener. Update custom rules, inspect the fields' validity, write their messages, and prevent submission when any fail. Move focus to the first invalid field or to a linked error summary. If JavaScript handles successful submission locally too, cancel that default submission as well.

Avoid reporting incomplete email text on every initial keystroke. A useful sequence is to show errors after blur or submission, then recheck an already reported error on input.

A control needs more than a click response. People must be able to find it, reach it, understand its purpose, operate it, and see where focus is. Native HTML supplies much of this behavior already.

Choose the element for the job

Use a <button> for an action, an <a href> for navigation, and a labeled form control for input. <details> with <summary> supplies a disclosure. Style these elements with CSS to match the page. A focused button activates through Enter or Space without an extra key listener.

A div with a click listener has none of the button's built-in semantics or keyboard behavior. Giving it role="button" changes what assistive technology announces, but does not make it focusable or turn key presses into clicks.

Keep the focus order predictable

tabindex="0" adds an element to the normal document-order Tab sequence. tabindex="-1" permits programmatic focus without adding a Tab stop. Positive values move elements ahead of the usual sequence and are difficult to maintain; avoid them.

Neither setting adds activation behavior. A focusable custom button still needs a listener for its keyboard operation. A role, a Tab stop, and a callback solve different parts of the interaction.

Give every control a name

A screen reader uses an accessible name to distinguish controls. A text button can use its visible text. A text field or select needs an associated label, such as <label for="email">Email</label> paired with id="email". aria-labelledby can refer to visible text elsewhere; aria-label can supply a name when there is no suitable visible text.

An icon-only close button can be <button type="button" aria-label="Close">×</button>. The name describes the action instead of making the user infer what the symbol means.

Show and enforce state

Keep a visible focus indicator. If you replace the default outline, supply a clear replacement with :focus-visible, for example outline: 3px solid #1a73e8. Removing it without replacement hides the keyboard user's position.

A native disabled button leaves the Tab sequence and cannot be activated normally. aria-disabled="true" only communicates unavailability. A custom control's click and keyboard action must check that state and return without acting. Centralizing that check in the activation function keeps both input routes consistent.

A custom control should give the same result regardless of how it is activated. Keep the action in one function, route keyboard and pointer use to it, and update the state that both styling and assistive technology read.

Give a custom button keyboard activation

fakeButton.addEventListener("click", activate);
fakeButton.addEventListener("keydown", (event) => {
  if (event.key === "Enter" || event.key === " ") {
    event.preventDefault();
    activate();
  }
});

This is for a custom focusable button. Canceling Space prevents page scrolling during its action. A native button already produces clicks from keyboard activation, so adding a second key route to it can run the action twice.

Choose the state that matches the control

A "Mute" toggle keeps that label and changes aria-pressed. If the design changes its action label to "Unmute", leave out aria-pressed. A checkbox uses role="checkbox" and Space to toggle; a switch uses role="switch" for on/off state.

Attributes contain strings. Compare getAttribute("aria-expanded") with "true", not the Boolean true:

detailsButton.addEventListener("click", () => {
  const open = detailsButton.getAttribute(
    "aria-expanded") === "true";
  detailsButton.setAttribute("aria-expanded", String(!open));
  panel.hidden = open;
});

When open was true, the new state is false and the panel becomes hidden. aria-controls can identify the panel by ID. Native <details> and <summary> supply disclosure behavior without this script.

Use the state attribute as the styling source, such as [aria-pressed="true"], so the visible and announced states change together. Close popups on Escape and return focus to their opener.

Give a group one Tab stop

Tabs, toolbars, and radio groups use Tab to enter or leave the group and arrow keys to move inside it. Roving tabindex keeps the current item at 0 and other items at -1. On movement, set the old item to -1, the new item to 0, and focus the new item.

For three items, right from index 2 wraps with (2 + 1) % 3 to 0. Left from 0 uses (0 - 1 + 3) % 3 to reach 2. Add the length before the remainder operation because JavaScript's -1 % 3 is −1.

Check with the keyboard: enter the control, see focus, activate it with the appropriate keys, move within a group, and close a popup with Escape. Check the visible state and the ARIA state on each change.

Focus decides where the next keyboard action goes. If the focused control disappears, the user can lose their place. Treat focus as part of the page update, especially when opening a dialog, deleting an item, or reporting an error.

Open a dialog and return to its opener

Remember the focused element before opening. Move into the new interaction, then restore focus on close:

let opener;
openButton.addEventListener("click", () => {
  opener = document.activeElement;
  dialog.showModal();
});
dialog.addEventListener("close", () => {
  if (opener && opener.isConnected) opener.focus();
});

showModal() on a native dialog moves focus inside and makes the rest of the page inert, so it cannot be clicked or focused while the modal is open. Escape normally causes a cancel event followed by closure and a close event. A cancel listener can prevent closing if the application needs that behavior.

Choose a useful initial focus location in the dialog, such as its first relevant control. For a custom popup, code must move focus deliberately. When the original opener no longer exists, choose a nearby useful control instead of trying to focus a detached element.

Make a useful destination focusable

A heading or error summary is not ordinarily focusable. Give it tabindex="-1" before calling .focus(). It can receive the deliberate focus move without becoming an extra stop during normal Tab navigation. Use 0 only when it belongs in that normal sequence.

Preserve position after deletion

Before removing a list item whose delete button has focus, find the next useful destination. Focus the next item's button; if there is no next item, use the previous item's button. If the list becomes empty, focus its heading with tabindex="-1".

Finding the destination before removal avoids losing the relationship to neighboring items. Do not send focus to the top of the document after every deletion; the person should be able to continue working near the change.

Keep focus within a continuing interaction

A popup may close when focus leaves its whole area. The bubbling focusout event provides the destination:

menu.addEventListener("focusout", (event) => {
  if (!menu.contains(event.relatedTarget)) {
    menu.hidden = true;
  }
});

Moving between two menu controls does not close it because the destination remains inside. A null destination is outside too; contains(null) is false. Do not automatically return focus to the opener when the user has intentionally moved to another page control.

Make changes predictable

After failed custom form validation, focus the first invalid field or an error summary that links to the errors. Built-in validation already focuses a failing field. Keep error text available so the person knows what to correct.

Do not jump to a new field while the user is typing or navigate as soon as a select changes. Let a clear action confirm the change. Focus movement should support a deliberate action or recovery, not interrupt ordinary input.