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.HistoryItemobjects 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.HistoryItemdata for that page. history.onVisitRemoved-
Fired when a URL is removed completely from the browser history.
Example extensions
Browser compatibility
| desktop | 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.
Note:
This API is based on Chromium's chrome.history API. This documentation is derived from history.json in the Chromium code.