Pointer & Keyboard

Handling pointer and keyboard input — native DOM events inside the plugin frame, and events forwarded from the host page

Because plugins run in a sandboxed iframe, they have direct access to the standard browser event system inside that frame. For most interactive plugins, native DOM event listeners are all you need.

The SDK also provides a forwarded event channel for input that originates outside the plugin frame but that the host decides to relay — useful for plugins that need to respond to global keyboard shortcuts or host-page gestures.

Native DOM Events

The plugin frame is a full browser document. Attach event listeners directly to your DOM elements using standard browser APIs:

internote.onInitialize(({ attrs, width, height }) => {
  const canvas = document.createElement('canvas')
  canvas.width = width
  canvas.height = height
  document.body.style.margin = '0'
  document.body.appendChild(canvas)

  canvas.addEventListener('pointerdown', (e) => {
    handleClick(e.offsetX, e.offsetY)
  })

  canvas.addEventListener('pointermove', (e) => {
    if (e.buttons > 0) handleDrag(e.offsetX, e.offsetY)
  })

  canvas.addEventListener('wheel', (e) => {
    handleZoom(e.deltaY)
  })

  internote.ready()
})

internote.onInitialize(({ attrs, width, height }) => {
  const canvas = document.createElement('canvas')
  canvas.width = width
  canvas.height = height
  document.body.style.margin = '0'
  document.body.appendChild(canvas)

  canvas.addEventListener('pointerdown', (e) => {
    handleClick(e.offsetX, e.offsetY)
  })

  canvas.addEventListener('pointermove', (e) => {
    if (e.buttons > 0) handleDrag(e.offsetX, e.offsetY)
  })

  canvas.addEventListener('wheel', (e) => {
    handleZoom(e.deltaY)
  })

  internote.ready()
})

JavaScript

Read-only

Every standard browser event API is available: pointer events, touch events, mouse events, wheel events, drag events. If your plugin renders a React component tree, use React's synthetic event system as you normally would.

Keyboard Focus

The plugin frame does not receive keyboard events unless it has focus. If your plugin needs keyboard input, request focus when the student first interacts with it:

canvas.setAttribute('tabindex', '0')

canvas.addEventListener('click', () => {
  canvas.focus()
})

canvas.addEventListener('keydown', (e) => {
  if (e.key === 'ArrowLeft') moveLeft()
  if (e.key === 'ArrowRight') moveRight()
  if (e.key === ' ') e.preventDefault(), togglePause()
})

canvas.setAttribute('tabindex', '0')

canvas.addEventListener('click', () => {
  canvas.focus()
})

canvas.addEventListener('keydown', (e) => {
  if (e.key === 'ArrowLeft') moveLeft()
  if (e.key === 'ArrowRight') moveRight()
  if (e.key === ' ') e.preventDefault(), togglePause()
})

JavaScript

Read-only

Pointer Lock

The sandbox permits the Pointer Lock API (allow-pointer-lock). Use it in plugins that need unrestricted mouse movement — 3D navigators, drawing tools, first-person simulations:

canvas.addEventListener('click', () => {
  canvas.requestPointerLock()
})

document.addEventListener('pointerlockchange', () => {
  if (document.pointerLockElement === canvas) {
    document.addEventListener('mousemove', onLockedMouseMove)
  } else {
    document.removeEventListener('mousemove', onLockedMouseMove)
  }
})

function onLockedMouseMove(e) {
  // e.movementX and e.movementY are available when locked
  rotateCameraBy(e.movementX, e.movementY)
}

canvas.addEventListener('click', () => {
  canvas.requestPointerLock()
})

document.addEventListener('pointerlockchange', () => {
  if (document.pointerLockElement === canvas) {
    document.addEventListener('mousemove', onLockedMouseMove)
  } else {
    document.removeEventListener('mousemove', onLockedMouseMove)
  }
})

function onLockedMouseMove(e) {
  // e.movementX and e.movementY are available when locked
  rotateCameraBy(e.movementX, e.movementY)
}

JavaScript

Read-only

Forwarded Events: onPointer

Registers a handler for pointer events forwarded from the host page — events that occurred on the internote page outside the plugin frame but which the runtime has relayed to the plugin.

handler (function; required). Called with a PluginPointerEvent object.
Returns void

internote.onPointer(({ type, x, y, pointerId, isPrimary }) => {
  if (type === 'pointerdown' && isPrimary) {
    handleHostPageClick(x, y)
  }
})

internote.onPointer(({ type, x, y, pointerId, isPrimary }) => {
  if (type === 'pointerdown' && isPrimary) {
    handleHostPageClick(x, y)
  }
})

JavaScript

Read-only

PluginPointerEvent

interface PluginPointerEvent {
  type: 'pointerdown' | 'pointermove' | 'pointerup'
  x: number         // Offset from the plugin element's left edge, in pixels
  y: number         // Offset from the plugin element's top edge, in pixels
  pointerId: number
  isPrimary: boolean
}

interface PluginPointerEvent {
  type: 'pointerdown' | 'pointermove' | 'pointerup'
  x: number         // Offset from the plugin element's left edge, in pixels
  y: number         // Offset from the plugin element's top edge, in pixels
  pointerId: number
  isPrimary: boolean
}

TypeScript

Read-only

onPointer receives events that originate outside the plugin frame. For events the student makes directly inside the plugin frame, use native addEventListener on your DOM elements — those events are richer and already properly scoped.

Forwarded Events: onKeyboard

Registers a handler for keyboard events forwarded from the host page. Useful when the plugin should respond to keyboard input even when its frame does not have focus — for example, advancing a simulation step in sync with the student navigating the internote.

handler (function; required). Called with a PluginKeyboardEvent object.
Returns void

internote.onKeyboard(({ type, key, repeat }) => {
  if (type === 'keydown' && !repeat) {
    if (key === 'ArrowRight') advanceStep()
    if (key === 'ArrowLeft') rewindStep()
    if (key === ' ') togglePause()
  }
})

internote.onKeyboard(({ type, key, repeat }) => {
  if (type === 'keydown' && !repeat) {
    if (key === 'ArrowRight') advanceStep()
    if (key === 'ArrowLeft') rewindStep()
    if (key === ' ') togglePause()
  }
})

JavaScript

Read-only

PluginKeyboardEvent

interface PluginKeyboardEvent {
  type: 'keydown' | 'keyup'
  key: string      // e.g. 'ArrowLeft', 'Enter', ' '
  code: string     // e.g. 'ArrowLeft', 'Space', 'KeyA'
  repeat: boolean  // true when the key is held down
}

interface PluginKeyboardEvent {
  type: 'keydown' | 'keyup'
  key: string      // e.g. 'ArrowLeft', 'Enter', ' '
  code: string     // e.g. 'ArrowLeft', 'Space', 'KeyA'
  repeat: boolean  // true when the key is held down
}

TypeScript

Read-only

Touch Support

Touch events and the Pointer Events API both work natively in the plugin frame. The Pointer Events API is recommended over the raw Touch Events API because it handles both mouse and touch with a unified interface:

canvas.addEventListener('pointerdown', (e) => {
  e.target.setPointerCapture(e.pointerId)
  startDrag(e.offsetX, e.offsetY)
})

canvas.addEventListener('pointermove', (e) => {
  if (e.buttons > 0) continueDrag(e.offsetX, e.offsetY)
})

canvas.addEventListener('pointerup', () => {
  endDrag()
})

canvas.addEventListener('pointerdown', (e) => {
  e.target.setPointerCapture(e.pointerId)
  startDrag(e.offsetX, e.offsetY)
})

canvas.addEventListener('pointermove', (e) => {
  if (e.buttons > 0) continueDrag(e.offsetX, e.offsetY)
})

canvas.addEventListener('pointerup', () => {
  endDrag()
})

JavaScript

Read-only

setPointerCapture ensures that pointermove and pointerup events are delivered to the canvas even if the pointer leaves its bounds during a drag — particularly important on touch devices.

On this page

Native DOM Events Keyboard Focus Pointer Lock Forwarded Events: onPointer Forwarded Events: onKeyboard Touch Support

Pointer & Keyboard

Handling pointer and keyboard input — native DOM events inside the plugin frame, and events forwarded from the host page

Because plugins run in a sandboxed iframe, they have direct access to the standard browser event system inside that frame. For most interactive plugins, native DOM event listeners are all you need.

Native DOM Events

The plugin frame is a full browser document. Attach event listeners directly to your DOM elements using standard browser APIs:

internote.onInitialize(({ attrs, width, height }) => {
  const canvas = document.createElement('canvas')
  canvas.width = width
  canvas.height = height
  document.body.style.margin = '0'
  document.body.appendChild(canvas)

  canvas.addEventListener('pointerdown', (e) => {
    handleClick(e.offsetX, e.offsetY)
  })

  canvas.addEventListener('pointermove', (e) => {
    if (e.buttons > 0) handleDrag(e.offsetX, e.offsetY)
  })

  canvas.addEventListener('wheel', (e) => {
    handleZoom(e.deltaY)
  })

  internote.ready()
})

internote.onInitialize(({ attrs, width, height }) => {
  const canvas = document.createElement('canvas')
  canvas.width = width
  canvas.height = height
  document.body.style.margin = '0'
  document.body.appendChild(canvas)

  canvas.addEventListener('pointerdown', (e) => {
    handleClick(e.offsetX, e.offsetY)
  })

  canvas.addEventListener('pointermove', (e) => {
    if (e.buttons > 0) handleDrag(e.offsetX, e.offsetY)
  })

  canvas.addEventListener('wheel', (e) => {
    handleZoom(e.deltaY)
  })

  internote.ready()
})

JavaScript

Read-only

Keyboard Focus

The plugin frame does not receive keyboard events unless it has focus. If your plugin needs keyboard input, request focus when the student first interacts with it:

canvas.setAttribute('tabindex', '0')

canvas.addEventListener('click', () => {
  canvas.focus()
})

canvas.addEventListener('keydown', (e) => {
  if (e.key === 'ArrowLeft') moveLeft()
  if (e.key === 'ArrowRight') moveRight()
  if (e.key === ' ') e.preventDefault(), togglePause()
})

canvas.setAttribute('tabindex', '0')

canvas.addEventListener('click', () => {
  canvas.focus()
})

canvas.addEventListener('keydown', (e) => {
  if (e.key === 'ArrowLeft') moveLeft()
  if (e.key === 'ArrowRight') moveRight()
  if (e.key === ' ') e.preventDefault(), togglePause()
})

JavaScript

Read-only

Pointer Lock

The sandbox permits the Pointer Lock API (allow-pointer-lock). Use it in plugins that need unrestricted mouse movement — 3D navigators, drawing tools, first-person simulations:

canvas.addEventListener('click', () => {
  canvas.requestPointerLock()
})

document.addEventListener('pointerlockchange', () => {
  if (document.pointerLockElement === canvas) {
    document.addEventListener('mousemove', onLockedMouseMove)
  } else {
    document.removeEventListener('mousemove', onLockedMouseMove)
  }
})

function onLockedMouseMove(e) {
  // e.movementX and e.movementY are available when locked
  rotateCameraBy(e.movementX, e.movementY)
}

canvas.addEventListener('click', () => {
  canvas.requestPointerLock()
})

document.addEventListener('pointerlockchange', () => {
  if (document.pointerLockElement === canvas) {
    document.addEventListener('mousemove', onLockedMouseMove)
  } else {
    document.removeEventListener('mousemove', onLockedMouseMove)
  }
})

function onLockedMouseMove(e) {
  // e.movementX and e.movementY are available when locked
  rotateCameraBy(e.movementX, e.movementY)
}

JavaScript

Read-only

Forwarded Events: onPointer

Registers a handler for pointer events forwarded from the host page — events that occurred on the internote page outside the plugin frame but which the runtime has relayed to the plugin.

handler (function; required). Called with a PluginPointerEvent object.
Returns void

internote.onPointer(({ type, x, y, pointerId, isPrimary }) => {
  if (type === 'pointerdown' && isPrimary) {
    handleHostPageClick(x, y)
  }
})

internote.onPointer(({ type, x, y, pointerId, isPrimary }) => {
  if (type === 'pointerdown' && isPrimary) {
    handleHostPageClick(x, y)
  }
})

JavaScript

Read-only

PluginPointerEvent

interface PluginPointerEvent {
  type: 'pointerdown' | 'pointermove' | 'pointerup'
  x: number         // Offset from the plugin element's left edge, in pixels
  y: number         // Offset from the plugin element's top edge, in pixels
  pointerId: number
  isPrimary: boolean
}

interface PluginPointerEvent {
  type: 'pointerdown' | 'pointermove' | 'pointerup'
  x: number         // Offset from the plugin element's left edge, in pixels
  y: number         // Offset from the plugin element's top edge, in pixels
  pointerId: number
  isPrimary: boolean
}

TypeScript

Read-only

Forwarded Events: onKeyboard

handler (function; required). Called with a PluginKeyboardEvent object.
Returns void

internote.onKeyboard(({ type, key, repeat }) => {
  if (type === 'keydown' && !repeat) {
    if (key === 'ArrowRight') advanceStep()
    if (key === 'ArrowLeft') rewindStep()
    if (key === ' ') togglePause()
  }
})

internote.onKeyboard(({ type, key, repeat }) => {
  if (type === 'keydown' && !repeat) {
    if (key === 'ArrowRight') advanceStep()
    if (key === 'ArrowLeft') rewindStep()
    if (key === ' ') togglePause()
  }
})

JavaScript

Read-only

PluginKeyboardEvent

interface PluginKeyboardEvent {
  type: 'keydown' | 'keyup'
  key: string      // e.g. 'ArrowLeft', 'Enter', ' '
  code: string     // e.g. 'ArrowLeft', 'Space', 'KeyA'
  repeat: boolean  // true when the key is held down
}

interface PluginKeyboardEvent {
  type: 'keydown' | 'keyup'
  key: string      // e.g. 'ArrowLeft', 'Enter', ' '
  code: string     // e.g. 'ArrowLeft', 'Space', 'KeyA'
  repeat: boolean  // true when the key is held down
}

TypeScript

Read-only

Touch Support

canvas.addEventListener('pointerdown', (e) => {
  e.target.setPointerCapture(e.pointerId)
  startDrag(e.offsetX, e.offsetY)
})

canvas.addEventListener('pointermove', (e) => {
  if (e.buttons > 0) continueDrag(e.offsetX, e.offsetY)
})

canvas.addEventListener('pointerup', () => {
  endDrag()
})

canvas.addEventListener('pointerdown', (e) => {
  e.target.setPointerCapture(e.pointerId)
  startDrag(e.offsetX, e.offsetY)
})

canvas.addEventListener('pointermove', (e) => {
  if (e.buttons > 0) continueDrag(e.offsetX, e.offsetY)
})

canvas.addEventListener('pointerup', () => {
  endDrag()
})

JavaScript

Read-only

setPointerCapture ensures that pointermove and pointerup events are delivered to the canvas even if the pointer leaves its bounds during a drag — particularly important on touch devices.

On this page

Native DOM Events Keyboard Focus Pointer Lock Forwarded Events: onPointer Forwarded Events: onKeyboard Touch Support