chrome.alarms

Chrome 120: Starting in Chrome 120, the minimum alarm interval has been reduced from 1 minute to 30 seconds. For an alarm to trigger in 30 seconds, setperiodInMinutes: 0.5.
Chrome 117: Starting in Chrome 117, the number of active alarms is limited to 500. Once this limit is reached,chrome.alarms.create() will fail. When using a callback,chrome.runtime.lastError will be set. When using promises, the promise will be rejected.

Description

Use thechrome.alarms API to schedule code to run periodically or at a specified time in the future.

Permissions

alarms

To use thechrome.alarms API, declare the"alarms" permission in themanifest:

{"name":"My extension",..."permissions":["alarms"],...}

Concepts and usage

To ensure reliable behavior, it is helpful to understand how the API behaves.

Device sleep

Alarms continue to run while a device is sleeping. However, an alarm will notwake up a device. When the device wakes up, any missed alarms will fire.Repeating alarms will fire at most once and then be rescheduled using thespecified period starting from when the device wakes, not taking into accountany time that has already elapsed since the alarm was originally set to run.

Persistence

Alarms generally persist until an extension is updated. However, this is not guaranteed, and alarmsmay be cleared when the browser is restarted. Consequently, consider setting a value in storagewhen an alarm is created, and then ensure it exists each time your service worker starts up. For example:

constSTORAGE_KEY="user-preference-alarm-enabled";asyncfunctioncheckAlarmState(){const{alarmEnabled}=awaitchrome.storage.get(STORAGE_KEY);if(alarmEnabled){constalarm=awaitchrome.alarms.get("my-alarm");if(!alarm){awaitchrome.alarms.create({periodInMinutes:1});}}}checkAlarmState();

Examples

The following examples show how to use and respond to an alarm. To try this API,install theAlarm API example from thechrome-extension-samplesrepository.

Set an alarm

The following example sets an alarm in the service worker when the extension is installed:

service-worker.js:

chrome.runtime.onInstalled.addListener(async({reason})=>{if(reason!=='install'){return;}// Create an alarm so we have something to look at in the demoawaitchrome.alarms.create('demo-default-alarm',{delayInMinutes:1,periodInMinutes:1});});

Respond to an alarm

The following example sets theaction toolbar icon based on the name of the alarm that went off.

service-worker.js:

chrome.alarms.onAlarm.addListener((alarm)=>{chrome.action.setIcon({path:getIconPath(alarm.name),});});

Types

Alarm

Properties

  • name

    string

    Name of this alarm.

  • periodInMinutes

    number optional

    If not null, the alarm is a repeating alarm and will fire again inperiodInMinutes minutes.

  • scheduledTime

    number

    Time at which this alarm was scheduled to fire, in milliseconds past the epoch (e.g.Date.now() + n). For performance reasons, the alarm may have been delayed an arbitrary amount beyond this.

AlarmCreateInfo

Properties

  • delayInMinutes

    number optional

    Length of time in minutes after which theonAlarm event should fire.

  • periodInMinutes

    number optional

    If set, the onAlarm event should fire everyperiodInMinutes minutes after the initial event specified bywhen ordelayInMinutes. If not set, the alarm will only fire once.

  • when

    number optional

    Time at which the alarm should fire, in milliseconds past the epoch (e.g.Date.now() + n).

Methods

clear()

Promise
chrome.alarms.clear(
  name?: string,
  callback?: function,
)

Clears the alarm with the given name.

Parameters

  • name

    string optional

    The name of the alarm to clear. Defaults to the empty string.

  • callback

    function optional

    Thecallback parameter looks like:

    (wasCleared: boolean) => void

    • wasCleared

      boolean

Returns

  • Promise<boolean>

    Chrome 91+

    Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

clearAll()

Promise
chrome.alarms.clearAll(
  callback?: function,
)

Clears all alarms.

Parameters

  • callback

    function optional

    Thecallback parameter looks like:

    (wasCleared: boolean) => void

    • wasCleared

      boolean

Returns

  • Promise<boolean>

    Chrome 91+

    Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

create()

Promise
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

Creates an alarm. Near the time(s) specified byalarmInfo, theonAlarm event is fired. If there is another alarm with the same name (or no name if none is specified), it will be cancelled and replaced by this alarm.

In order to reduce the load on the user's machine, Chrome limits alarms to at most once every 30 seconds but may delay them an arbitrary amount more. That is, settingdelayInMinutes orperiodInMinutes to less than0.5 will not be honored and will cause a warning.when can be set to less than 30 seconds after "now" without warning but won't actually cause the alarm to fire for at least 30 seconds.

To help you debug your app or extension, when you've loaded it unpacked, there's no limit to how often the alarm can fire.

Parameters

  • name

    string optional

    Optional name to identify this alarm. Defaults to the empty string.

  • Describes when the alarm should fire. The initial time must be specified by eitherwhen ordelayInMinutes (but not both). IfperiodInMinutes is set, the alarm will repeat everyperiodInMinutes minutes after the initial event. If neitherwhen ordelayInMinutes is set for a repeating alarm,periodInMinutes is used as the default fordelayInMinutes.

  • callback

    function optional

    Chrome 111+

    Thecallback parameter looks like:

    () => void

Returns

  • Promise<void>

    Chrome 111+

    Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

get()

Promise
chrome.alarms.get(
  name?: string,
  callback?: function,
)

Retrieves details about the specified alarm.

Parameters

  • name

    string optional

    The name of the alarm to get. Defaults to the empty string.

  • callback

    function optional

    Thecallback parameter looks like:

    (alarm?: Alarm) => void

Returns

  • Promise<Alarm | undefined>

    Chrome 91+

    Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

getAll()

Promise
chrome.alarms.getAll(
  callback?: function,
)

Gets an array of all the alarms.

Parameters

  • callback

    function optional

    Thecallback parameter looks like:

    (alarms: Alarm[]) => void

Returns

  • Promise<Alarm[]>

    Chrome 91+

    Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

Events

onAlarm

chrome.alarms.onAlarm.addListener(
  callback: function,
)

Fired when an alarm has elapsed. Useful for event pages.

Parameters

  • callback

    function

    Thecallback parameter looks like:

    (alarm: Alarm) => void

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2024-05-24 UTC.