use-visibility.md

useVisibility

useVisibility tracks the visibility state of the page.

Adds two new behaviors to your Stimulus controller: visible and invisible.

Reference

useVisibility(controller, options)

controller : a Stimulus Controller (usually 'this')

options :

Option	Description	Default value
dispatchEvent	Whether to dispatch a click:outside event or not.	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

Example :

A typical use case would be to pause a video when the user navigate tabs.

// video_controller.js

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

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

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

Usage

Composing

import { Controller } from 'stimulus'
import { useVisibility } from 'stimulus-use'

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

  visible() {
    // triggered when the page is visible
  }

  invisible() {
    // triggered when the page is invisible
  }
}

Extending a controller

import { VisibilityController } from 'stimulus-use'

export default class extends VisibilityController {
  visible() {
    // triggered when the page is visible
  }

  invisible() {
    // triggered when the page is invisible
  }
}

Events

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

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

// application_controller.js

export default class extends Controller {

  connect() {
    useVisibility(this, { eventPrefix: false })
  }
}