useWindowFocus

useWindowFocus tracks if the window is focused or not.

Adds two new behaviors to your Stimulus controller: focus and unfocus.

Reference

useWindowFocus(controller, options)

controller : a Stimulus Controller (usually 'this')

options :

Option	Description	Default value
dispatchEvent	Whether to dispatch the focus / unfocus events or not (prefixed by the controller identifier by default, e.g. application:focus).	true
eventPrefix	Whether to prefix or not the emitted event. Can be a boolean or a string. - true prefix the event with the controller identifier application:visible - someString prefix the event with the given string someString:invisible - false to remove prefix	true
debug	Whether to log debug information. See debug for more information on the debugging tools	false
interval	The interval in ms to check if the window is focused or not.	200

Example :

A typical use case would be to pause a video when the user navigate tabs. While use-visibility just checks if the window might be visible useWindowFocus actually checks if the window is focused or not.

// video_controller.js

export default class extends Controller {
  connect() {
    useWindowFocus(this)
    this.player = new VideoPlayer()
  }

  focus() {
    this.player.play()
  }

  unfocus() {
    this.player.pause()
  }
}

Usage

Composing

import { Controller } from '@hotwired/stimulus'
import { useWindowFocus } from 'stimulus-use'

export default class extends Controller {
  connect() {
    useWindowFocus(this)
  }

  focus() {
    // triggered when the window is focused
  }

  unfocus() {
    // triggered when the window is unfocused
  }
}

Extending a controller

import { WindowFocusController } from 'stimulus-use'

export default class extends WindowFocusController {
  focus() {
    // triggered when the window is focused
  }

  unfocus() {
    // triggered when the window is unfocused
  }
}

Controlling observation

useWindowFocus returns an [observe, unobserve] tuple so you can start and stop observing manually. Observation starts automatically and is cleaned up when the controller disconnects. When extending WindowFocusController, the same functions are available as this.observe() and this.unobserve().

import { Controller } from '@hotwired/stimulus'
import { useWindowFocus } from 'stimulus-use'

export default class extends Controller {
  connect() {
    const [observe, unobserve] = useWindowFocus(this)
    this.observe = observe
    this.unobserve = unobserve
  }
}

State

useWindowFocus adds a hasFocus boolean property to the controller, reflecting whether the window is currently focused. You can read it anywhere in the controller:

if (this.hasFocus) {
  // the window is currently focused
}

Events

This module adds two new events focus and unfocus (prefixed by the controller identifier by default) event that you may use to triggers Stimulus actions.

Both events carry an event.detail of the shape { event, hasFocus }, where hasFocus is a boolean.

<div class="player" data-controller="player" data-action="focus@document->player#play unfocus@document->player#pause">
  ...
</div>

// application_controller.js

export default class extends Controller {
  connect() {
    useWindowFocus(this, { eventPrefix: false })
  }
}