alarms.create()

Creates a new alarm for the current browser session. An alarm may fire once or multiple times. An alarm is cleared after it fires for the last time.

[!NOTE] From Chrome 117, the number of active alarms is limited to 500. When this limit is reached, alarm creation fails.

Syntax

browser.alarms.create(
  name,              // optional string
  alarmInfo          // optional object
)

Parameters

• name {{optional_inline}}

  • : string. A name for the alarm. Defaults to the empty string.

    This can be used to refer to a particular alarm in {{WebExtAPIRef('alarms.get()')}} and {{WebExtAPIRef('alarms.clear()')}}. It will also be available in {{WebExtAPIRef('alarms.onAlarm')}} as the name property of the {{WebExtAPIRef('alarms.Alarm')}} object passed into the listener function.

    Alarm names are unique within the scope of a single extension. If an alarm with an identical name exists, the existing alarm will be cleared and the alarm being created will replace it.

• alarmInfo {{optional_inline}}

  • : object. You can use this to specify when the alarm will initially fire, either as an absolute value (when), or as a delay from the time the alarm is set (delayInMinutes). To make the alarm recur, specify periodInMinutes.

    In Chrome, unless the extension is loaded unpackaged, alarms do not fire more than once every 30 seconds. If an extension sets delayInMinutes to a value < 0.5, or when to a value < 0.5, the alarm fires 30 seconds after it is set. If an extension sets periodInMinutes to a value < 0.5, then the alarm fires every 30 seconds. Setting delayInMinutes or periodInMinutes to < 0.5 causes a warning. Alarm firings can be arbitrarily delayed. Before Chrome 120, this limit was one minute.

    The alarmInfo object may contain the following properties:

    • when {{optional_inline}}
      • : double. The time the alarm will fire first, given as milliseconds since the epoch. To get the number of milliseconds between the epoch and the current time, use Date.now(). If you specify when, don't specify delayInMinutes.
    • delayInMinutes {{optional_inline}}
      • : double. The time the alarm will fire first, given as minutes from the time the alarm is set. If you specify delayInMinutes, don't specify when.
    • periodInMinutes {{optional_inline}}
      • : double. If this is specified, the alarm will fire again every periodInMinutes after its initial firing. If you specify this value you may omit both when and delayInMinutes, and the alarm will then fire initially after periodInMinutes. If periodInMinutes is not specified, the alarm will only fire once.

Return value

A Promise that is fulfilled with no arguments.

Examples

Create a one-time delay-based alarm with "" for the name:

function onAdded() {
  console.log("Alarm Added!");
}

let delayInMinutes = 5;

let addingAlarm = browser.alarms.create({
  delayInMinutes,
});
addingAlarm.then(onAdded);

Create a periodic delay-based alarm named "my-periodic-alarm":

const delayInMinutes = 5;
const periodInMinutes = 2;

browser.alarms.create("my-periodic-alarm", {
  delayInMinutes,
  periodInMinutes,
});

Create a periodic absolute alarm named "my-periodic-alarm":

const when = 1545696000;
const periodInMinutes = 2;

browser.alarms.create("my-periodic-alarm", {
  when,
  periodInMinutes,
});

Browser compatibility

{{Compat}}

[!NOTE] This API is based on Chromium's chrome.alarms API.