Mouse, pointer & touch

One set of events for every kind of pointer

People point at a web page in many ways. Some use a mouse. Some touch a phone screen with a finger. Some draw on a tablet with a pen. Whatever the device, the page needs to know three things: where is the pointer, what is it doing, and should the page react?

This lesson covers three groups of browser events:

• Mouse events, such as click and mouseover. You still use them for normal clicks, hover, and right-click menus.
• Pointer events, such as pointerdown. They work the same way for a mouse, a pen, and a finger.
• Drag-and-drop events, such as dragstart and drop. The browser uses them to move an item into a drop area.

const event = {
  pointerType: "touch",
  pointerId: 7,
  isPrimary: true,
};

console.log(event.pointerType);
console.log(event.pointerId);
console.log(event.isPrimary);

This code makes a small object shaped like a real pointer event. Lines 7 to 9 print three of its properties. In plain words, line by line:

1. Line 2: pointerType is "touch", so a finger made this event.
2. Line 3: pointerId is 7. Every pointer on the screen gets its own id number. If two fingers touch the screen, each finger has a different id, so your code can tell them apart.
3. Line 4: isPrimary is true. The first finger to touch the screen is the primary pointer. A drawing app can follow only the primary pointer and ignore a second finger.

The console prints touch, 7, and true.

One click with the main mouse button is not one event. It is several events in a row. In most browsers, the order is:

1. pointerdown: the button goes down.
2. mousedown: the same press, sent again as a mouse event.
3. pointerup: the button comes back up.
4. mouseup: the same release, sent again as a mouse event.
5. click: the press and the release together count as one click.

Buttons other than the main one send auxclick instead of click. "Aux" is short for auxiliary, which means "extra". The right button usually also sends contextmenu, which asks for the right-click menu. There is also dblclick, for a double-click. Use it only when the double-click itself matters.

const lifecycle = [
  "pointerdown",
  "pointermove",
  "pointerup",
  "click",
];

console.log(lifecycle.join(" -> "));

This small program only prints the event names in order: pointerdown -> pointermove -> pointerup -> click. In a real click, the pointer may move many times between the press and the release, or not at all. The rule to remember: click comes after the button is released. So if a drag should start the moment the button goes down, listen for pointerdown, not click.

Most mice have three buttons. This lesson calls them the main button (usually the left one, also called primary), the middle button (usually the wheel, also called auxiliary), and the secondary button (usually the right one). Mouse and pointer events have two properties with almost the same name, and they answer different questions:

• button answers "Which button changed in this event?" It is 0 for the main button, 1 for the middle button, and 2 for the secondary button.
• buttons answers "Which buttons are held down right now?" Each button has its own number: 1 for the main button, 2 for the secondary button, and 4 for the middle button. JavaScript adds up the numbers of all held buttons. So 3 means 1 + 2: the main and secondary buttons are both down. A number built this way is called a bitmask.

While the pointer moves, no button changes. So in mousemove and pointermove, buttons is usually the property you want.

1pad.addEventListener("pointermove", (event) => {2  show("pointerType", event.pointerType);3  show("pointerId", event.pointerId);4  show("isPrimary", event.isPrimary);5  show("button", event.button);6  show("buttons", event.buttons);7  show("pressure", event.pressure);8});

To build your own right-click menu, listen for contextmenu, not only mousedown. Call preventDefault() in that listener to stop the browser's own menu. If you do, give keyboard users and screen-reader users another way to reach the same actions. The next lesson, Keyboard & focus, shows how.

1const event = {Run2  pointerType: "mouse",3  pointerId: 1,4  isPrimary: true,5  button: 0,6  buttons: 1,7};8 9console.log(event.pointerType);10console.log(event.button);11console.log(event.buttons);

Hover events fire when the pointer crosses the edge of an element. There are two pairs of them, and they behave differently:

• mouseover and mouseout bubble. Bubbling means an event on a child element also reaches its parent. So when the pointer moves from one child to another inside a card, the card hears a new mouseover each time.
• mouseenter and mouseleave do not bubble. The card hears mouseenter once when the pointer comes into the card, and mouseleave once when it goes out.

mouseover and mouseout also have a relatedTarget property. It is the other element in the move: where the pointer came from, or where it is going. That helps when one listener on a parent handles many children (event delegation). But for a card with an icon, a title, and a button inside, all those extra events are just noise.

1const parent = document.querySelector(".card");2 3parent.addEventListener("mouseover", (event) => {4  console.log("over", event.target.className);5  console.log("from", event.relatedTarget?.className ?? "outside");6});7 8parent.addEventListener("mouseenter", () => {9  console.log("entered the whole card");10});

Pointer events have the same two pairs:

• pointerover and pointerout bubble, like mouseover and mouseout.
• pointerenter and pointerleave do not bubble, like mouseenter and mouseleave.

Use the mouse names when your code only cares about a mouse. Use the pointer names when the same widget must also work with a pen or a finger.

These are the pointer events:

• pointerdown, pointermove, and pointerup: press, move, and release.
• pointercancel: the browser stopped sending this pointer's events. You'll see why below.
• pointerover, pointerout, pointerenter, and pointerleave: the hover pairs from the last section.

They look like mouse events, but they carry extra properties about the device: pointerId, pointerType, isPrimary, pressure, and more.

After most pointer events, the browser also sends the matching mouse event, such as mousedown after pointerdown. These extra events are called compatibility mouse events. They exist so that older code written only for a mouse still works. So don't run the same action in both a pointerdown listener and a mousedown listener: it would run twice. For drawing, sliders, resizing, and gestures, pick pointer events.

Here is a common case. On a phone, a finger starts on your slider. Then it moves far enough that the browser thinks the user wants to scroll the page. The browser takes over, and your code gets pointercancel instead of pointerup. So clean up the drag in both cases, on pointerup and on pointercancel.

let dragging = true;

function finishGesture(eventType) {
  dragging = false;
  console.log(eventType, dragging);
}

finishGesture("pointercancel");

Line 1 says a drag is going on: dragging is true. The finishGesture function on lines 3 to 6 sets dragging back to false. You can call it for either ending event. Line 8 calls it for pointercancel, so the console prints pointercancel false. Without this cleanup, a canceled slider can stay stuck, still looking as if it is being dragged.

When a control really needs the touch gesture for itself, add one CSS rule to it:

.custom-slider {
  touch-action: none;
}

The table below sums up the choices so far. Each row is one question your code might ask; read across to see what answers it.

Dragging can break if the pointer has to stay exactly over the small thing you drag. Take a slider's thumb, the knob you drag. A fast hand can leave the thumb before the next move event arrives. Then the thumb stops getting moves, and it stops.

Pointer capture fixes this. When you call thumb.setPointerCapture(event.pointerId), every later event from that pointer goes to the thumb, even when the pointer is somewhere else. Capture ends by itself after pointerup. You can also end it yourself with releasePointerCapture().

1thumb.addEventListener("pointerdown", (event) => {2  thumb.setPointerCapture(event.pointerId);3  drag(event.clientX);4});5 6thumb.addEventListener("pointermove", (event) => {7  if (event.buttons === 1) drag(event.clientX);8});9 10thumb.addEventListener("pointerup", (event) => {11  thumb.releasePointerCapture(event.pointerId);12});

1thumb.addEventListener("pointerdown", (event) => {2  thumb.setPointerCapture(event.pointerId);3  drag(event.clientX);4});5 6thumb.addEventListener("pointermove", (event) => {7  if (event.buttons === 1) drag(event.clientX);8});9 10thumb.addEventListener("pointerup", (event) => {11  thumb.releasePointerCapture(event.pointerId);12});

Line 2 starts the capture when the button goes down. Line 7 moves the thumb only while the main button is held (buttons === 1). Line 11 ends the capture when the button comes up.

1card.addEventListener("pointerdown", (event) => {2  card.setPointerCapture(event.pointerId);3  card.classList.add("dragging");4});5 6card.addEventListener("pointerup", (event) => {7  card.releasePointerCapture(event.pointerId);8  card.classList.remove("dragging");9});

Line 2 captures the pointer when the press starts, so the drag keeps working outside the card. Line 3 adds the dragging class, which only changes how the card looks. A real app would also move the card in a pointermove listener. Line 7 releases the capture when the press ends. Always release capture when the gesture ends or is canceled.

HTML drag and drop is a different set of events. It moves data from the item you drag (the source) to the place you drop it (the target). It takes four steps:

1. Mark the source as draggable: draggable="true" in HTML, or card.draggable = true in JavaScript.
2. In the source's dragstart listener, save some data with event.dataTransfer.setData(). dataTransfer is the object that carries data during a drag.
3. In the target's dragover listener, call preventDefault(). This tells the browser the target accepts drops. Many apps do the same in dragenter.
4. In the target's drop listener, read the data with getData() and move the item.

While the drag is going on, the browser protects the data so that other code can't read it. That is why you can read your data in drop, but not in dragover.

1card.draggable = true;2 3card.addEventListener("dragstart", (event) => {4  event.dataTransfer.setData("text/plain", card.id);5});6 7target.addEventListener("dragover", (event) => {8  event.preventDefault();9});10 11target.addEventListener("drop", (event) => {12  const id = event.dataTransfer.getData("text/plain");13  target.append(document.getElementById(id));14});

1card.draggable = true;2 3card.addEventListener("dragstart", (event) => {4  event.dataTransfer.setData("text/plain", card.id);5});6 7target.addEventListener("dragover", (event) => {8  event.preventDefault();9});10 11target.addEventListener("drop", (event) => {12  const id = event.dataTransfer.getData("text/plain");13  target.append(document.getElementById(id));14});

Line 1 makes the card draggable. Line 4 saves the card's id when the drag starts. Line 8 accepts the drop on the target. Lines 12 and 13 read the id and move the card into the target.

Real apps often mix these events:

• A drawing app uses pointer events, so it works with a mouse, a pen, and a finger.
• A splitter, the bar you drag to resize two panels, captures the pointer. It keeps resizing even when your hand moves faster than the bar.
• A file manager might use HTML drag and drop on a desktop, and pointer events on touch screens.

1element.addEventListener("pointerdown", (event) => {2  if (event.button !== 0) return;3  element.setPointerCapture(event.pointerId);4});5 6element.addEventListener("pointermove", (event) => {7  if (event.buttons !== 1) return;8  drawLineTo(event.clientX, event.clientY);9});

Line 2 ignores any press that is not the main button (button is not 0). Line 3 captures the pointer. Line 7 skips moves when the main button is not held. Line 8 draws to the pointer's position.

1const canvas = document.querySelector("canvas");2const context = canvas.getContext("2d");3 4canvas.addEventListener("pointerdown", (event) => {5  context.beginPath();6  context.moveTo(event.offsetX, event.offsetY);7});8 9canvas.addEventListener("pointermove", (event) => {10  if (event.buttons !== 1) return;11  context.lineTo(event.offsetX, event.offsetY);12  context.stroke();13});

A <canvas> is an HTML element that JavaScript can draw on. This code works the same for a finger, a mouse, or a pen:

• Lines 4 to 7: pointerdown starts a new line at the pointer's spot.
• Lines 9 to 13: pointermove adds to the line, but only while the main button is held (line 10).
• The page's CSS gives the canvas touch-action: none, so a finger draws instead of scrolling the page.

A full version would also listen for pointerup and pointercancel to end the line.

Common misconceptions

• "Pointer events are the CSS pointer-events property." No. Pointer events are JavaScript events, such as pointerdown. The CSS property pointer-events is something else: it decides whether an element can be clicked or hovered at all.
• "button and buttons mean the same thing." No. button is the one button that changed. buttons adds up every button held right now.
• "mouseenter bubbles like mouseover." It does not. A parent does not hear mouseenter from its children. If one listener on a parent should handle many children, use mouseover.
• "Pointer capture captures every pointer." No. It captures one pointer, chosen by its pointerId, for one element.
• "HTML drag and drop works the same on every touch screen." No. Touch support differs between devices. Test on real phones, and think about using pointer events for touch dragging.
• "A drop listener is enough." No. The browser normally fires drop only on a target that called preventDefault() during dragover.

Key takeaways

• Mouse events still matter for clicks, hover, other-button clicks (auxclick), and right-click menus (contextmenu).
• button says which button changed. buttons says which buttons are held now.
• mouseover and mouseout bubble. mouseenter and mouseleave do not.
• Pick pointer events for custom controls that must work with a mouse, a pen, and a finger.
• Pointer capture sends one pointer's events to one element for the whole drag.
• HTML drag and drop needs preventDefault() in dragover, and it works differently on touch screens.

Final definition: Pointer events are browser events about one mouse, pen, or touch point. They use the same set of events for every device.

Up next: Keyboard & focus.