Web/API/Clients

The Clients interface provides access to Client objects. Access it via self.clients within a service worker.

Methods

Clients.get(): Returns a Promise for a Client matching a given id.
Clients.matchAll(): Returns a Promise for an array of Client objects. An options argument allows you to control the types of clients returned.
Clients.openWindow(): Opens a new browser window for a given url and returns a Promise for the new WindowClient.
Clients.claim(): Allows an active service worker to set itself as the controller for all clients within its scope.

Examples

The following example shows an existing chat window or creates a new one when the user clicks a notification.

addEventListener('notificationclick', event => {
  event.waitUntil(async function() {
    const allClients = await clients.matchAll({
      includeUncontrolled: true
    });

    let chatClient;

    // Let's see if we already have a chat window open:
    for (const client of allClients) {
      const url = new URL(client.url);

      if (url.pathname == '/chat/') {
        // Excellent, let's use it!
        client.focus();
        chatClient = client;
        break;
      }
    }

    // If we didn't find an existing chat window,
    // open a new one:
    if (!chatClient) {
      chatClient = await clients.openWindow('/chat/');
    }

    // Message the client:
    chatClient.postMessage("New chat messages!");
  }());
});

Specifications

Specification	Status	Comment
Service WorkersThe definition of 'Clients' in that specification.	Working Draft	Initial definition

Browser compatibility

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`Clients` Experimental'	Chrome Full support 40	Edge Full support ≤79	Firefox Full support 44 Notes' Full support 44 Notes' Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API.	IE No support No	Opera Full support 27	Safari No support No	WebView Android Full support 40	Chrome Android Full support 40	Firefox Android Full support 44	Opera Android Full support 27	Safari iOS No support No	Samsung Internet Android Full support 4.0
`claim` Experimental'	Chrome Full support 42	Edge Full support ≤79	Firefox Full support 44 Notes' Full support 44 Notes' Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API.	IE No support No	Opera Full support 29	Safari No support No	WebView Android Full support 42	Chrome Android Full support 42	Firefox Android Full support 44	Opera Android Full support 29	Safari iOS No support No	Samsung Internet Android Full support 4.0
`get` Experimental'	Chrome Full support 51	Edge Full support ≤79	Firefox Full support 45 Notes' Full support 45 Notes' Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API.	IE No support No	Opera Full support 38	Safari No support No	WebView Android No support No	Chrome Android Full support 51	Firefox Android Full support 45	Opera Android Full support 41	Safari iOS No support No	Samsung Internet Android Full support 5.0
`matchAll` Experimental'	Chrome Full support 47 Notes' Full support 47 Notes' Notes' `Client` objects returned in most recent focus order.	Edge Full support ≤79 Notes' Full support ≤79 Notes' Notes' `Client` objects returned in most recent focus order.	Firefox Full support 44 Notes' Full support 44 Notes' Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API. Full support 54 Notes' Notes' `Client` objects returned in most recent focus order.	IE No support No	Opera Full support 32	Safari No support No	WebView Android Full support 47 Notes' Full support 47 Notes' Notes' `Client` objects returned in most recent focus order.	Chrome Android Full support 47 Notes' Full support 47 Notes' Notes' `Client` objects returned in most recent focus order.	Firefox Android Full support 44 Full support 44 Full support 54 Notes' Notes' `Client` objects returned in most recent focus order.	Opera Android Full support 32	Safari iOS No support No	Samsung Internet Android Full support 4.0 Notes' Full support 4.0 Notes' Notes' `Client` objects returned in most recent focus order.
`openWindow` Experimental'	Chrome Full support 40 Full support 40 Full support 42 Notes' Notes' Can only open URLs on the same origin. Full support 43 Notes' Notes' Can open any URL. Full support 51 Notes' Notes' URLs may open inside an existing browsing context provided by a standalone web app	Edge Full support ≤79 Full support ≤79 Full support ≤79 Notes' Notes' Can only open URLs on the same origin. Full support ≤79 Notes' Notes' Can open any URL. Full support ≤79 Notes' Notes' URLs may open inside an existing browsing context provided by a standalone web app	Firefox Full support 45 Notes' Full support 45 Notes' Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API.	IE No support No	Opera Full support 38	Safari No support No	WebView Android Full support 40 Full support 40 Full support 42 Notes' Notes' Can only open URLs on the same origin. Full support 43 Notes' Notes' Can open any URL. Full support 51 Notes' Notes' URLs may open inside an existing browsing context provided by a standalone web app	Chrome Android Full support 40 Full support 40 Full support 42 Notes' Notes' Can only open URLs on the same origin. Full support 43 Notes' Notes' Can open any URL. Full support 51 Notes' Notes' URLs may open inside an existing browsing context provided by a standalone web app	Firefox Android Full support 45	Opera Android Full support 41	Safari iOS No support No	Samsung Internet Android Full support 4.0 Full support 4.0 Full support 5.0 Notes' Notes' URLs may open inside an existing browsing context provided by a standalone web app

Legend

Full support: Full support
No support: No support
Experimental. Expect behavior to change in the future.': Experimental. Expect behavior to change in the future.
See implementation notes.': See implementation notes.