chrome.alarms

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

Summary

Types
Alarm
AlarmCreateInfo
Methods
clear
clearAll
create
get
getAll
Events
onAlarm

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 in periodInMinutes 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 the onAlarm event should fire.
periodInMinutes
number optional
If set, the onAlarm event should fire every periodInMinutes minutes after the initial event specified by when or delayInMinutes. 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

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

Promise

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
The callback parameter looks like: (wasCleared: boolean) => void
- wasCleared
  boolean

Returns

Promise<boolean>
Pending
This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

clearAll

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

Promise

Clears all alarms.

Parameters

callback
function optional
The callback parameter looks like: (wasCleared: boolean) => void
- wasCleared
  boolean

Returns

Promise<boolean>
Pending
This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

create

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

Creates an alarm. Near the time(s) specified by alarmInfo, the onAlarm 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 1 minute but may delay them an arbitrary amount more. That is, setting delayInMinutes or periodInMinutes to less than 1 will not be honored and will cause a warning. when can be set to less than 1 minute after "now" without warning but won't actually cause the alarm to fire for at least 1 minute.

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.
alarmInfo
AlarmCreateInfo
Describes when the alarm should fire. The initial time must be specified by either when or delayInMinutes (but not both). If periodInMinutes is set, the alarm will repeat every periodInMinutes minutes after the initial event. If neither when or delayInMinutes is set for a repeating alarm, periodInMinutes is used as the default for delayInMinutes.

get

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

Promise

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
The callback parameter looks like: (alarm?: Alarm) => void
- alarm
  Alarm optional

Returns

Promise<Alarm | undefined>
Pending
This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

getAll

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

Promise

Gets an array of all the alarms.

Parameters

callback
function optional
The callback parameter looks like: (alarms: Alarm[]) => void
- alarms
  Alarm[]

Returns

Promise<Alarm[]>
Pending
This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

Events

onAlarm

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

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

Parameters

callback
function
The callback parameter looks like: (alarm: Alarm) => void
- alarm
  Alarm