history
Use the history
API to interact with the browser history.
If you are looking for information about the browser session history, see the History interface.
Note:
Downloads are treated as HistoryItem
objects. Therefore, events such as history.onVisited
fire for downloads.
Browser history is a chronological record of pages the user has visited. The history API enables you to:
- search for pages that appear in the browser history
- remove individual pages from the browser history
- add pages to the browser history
- remove all pages from the browser history.
However, the user may have visited a single page multiple times, so the API also has the concept of "visits". So you can also use this API to:
- retrieve the complete set of visits the user made to a particular page
- remove visits to any pages made during a given time period.
To use this API, an extension must request the "history" permission in its manifest.json
file.
Types
history.TransitionType
-
Describes how the browser navigated to a particular page.
history.HistoryItem
-
Provides information about a particular page in the browser history.
history.VisitItem
-
Describes a single visit to a page.
Functions
history.search()
-
Searches the browser history for
history.HistoryItem
objects matching the given criteria. history.getVisits()
-
Retrieves information about visits to a given page.
history.addUrl()
-
Adds a record to the browser history of a visit to the given page.
history.deleteUrl()
-
Removes all visits to the given URL from the browser history.
history.deleteRange()
-
Removes all visits to pages that the user made during the given time range.
history.deleteAll()
-
Removes all visits from the browser history.
Events
history.onTitleChanged
-
Fired when the title of a page visited by the user is recorded.
history.onVisited
-
Fired each time the user visits a page, providing the
history.HistoryItem
data for that page. history.onVisitRemoved
-
Fired when a URL is removed completely from the browser history.
Browser compatibility
Report problems with this compatibility data on GitHubdesktop | mobile | ||||||
---|---|---|---|---|---|---|---|
history | |||||||
HistoryItem | |||||||
HistoryItem.typedCount | |||||||
TransitionType | |||||||
VisitItem | |||||||
addUrl | |||||||
addUrl.title | |||||||
addUrl.transition | |||||||
addUrl.visitTime | |||||||
deleteAll | |||||||
deleteRange | |||||||
deleteUrl | |||||||
getVisits | |||||||
onTitleChanged | |||||||
onTitleChanged.id | |||||||
onVisitRemoved | |||||||
onVisited | |||||||
search |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- No support
- No support
- See implementation notes.
Example extensions
Note:
This API is based on Chromium's chrome.history
API. This documentation is derived from history.json
in the Chromium code.