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
BCD tables only load in the browser
Example extensions
Note: This API is based on Chromium's chrome.history
API. This documentation is derived from history.json
in the Chromium code.