Flashing page title

Flash the browser tab's title to draw users back to your page when something happens: new messages, finished uploads, incoming calls. Tiny, dependency-free and typed.

$ npm install flashing-page-title

Try it GitHub npm Read the blog post

Try it

NotificationInterval1000ms

flashingPageTitle.off();

Start it, then switch tabs: the real page title flashes too.

Usage

import { flashingPageTitle } from 'flashing-page-title';

// Flash "New Message!" every second
flashingPageTitle.on('New Message!', 1000);

// Stop flashing and restore the original title
flashingPageTitle.off();

<script type="module">
  import { flashingPageTitle } from 'https://esm.sh/flashing-page-title@3';

  flashingPageTitle.on('New Message!');
</script>

import { useEffect } from 'react';
import { createFlashingPageTitle } from 'flashing-page-title';

export function useFlashingTitle(text: string | null, interval = 1000) {
  useEffect(() => {
    if (!text) return;

    const notification = createFlashingPageTitle();
    notification.on(text, interval);

    return () => notification.off();
  }, [text, interval]);
}

// useFlashingTitle(unread > 0 ? `(${unread}) New messages` : null);

import { flashingPageTitle } from 'flashing-page-title';

// Only flash while the user is looking at another tab
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'visible') {
    flashingPageTitle.off();
  }
});

socket.on('message', () => {
  if (document.visibilityState === 'hidden') {
    flashingPageTitle.on('New Message!');
  }
});

API

flashingPageTitle

The ready-to-use flasher. Most apps only need this.

flashingPageTitle.on(text, interval?)

Starts flashing the tab title between text and the page's current title, swapping every interval milliseconds (default 1000). If it's already flashing, the call is ignored, so call off() first to change the text.

flashingPageTitle.off()

Stops flashing and puts the original title back. Safe to call when nothing is flashing.

createFlashingPageTitle()

Creates a separate flasher with the same on() / off(). You only need this when independent parts of your app might each flash the title, or to keep tests isolated: each one stops without affecting the others.

Migrating from 2.x

3.0 is an ES module only and no longer sets window.pageTitleNotification. The package was renamed from flashing-page-title-notification in 3.1, and its exports in 3.2 (pageTitleNotification → flashingPageTitle, createPageTitleNotification → createFlashingPageTitle). The old names still work until 4.0. Internet Explorer is no longer supported.

// 2.x: a global set by a <script> tag
window.pageTitleNotification.on('New Message!');

// 3.x: import it
import { flashingPageTitle } from 'flashing-page-title';
flashingPageTitle.on('New Message!');