chrome.readingList
Description
Use thechrome.readingList API to read from and modify the items in theReading List.
Permissions
readingListTo use the Reading List API, add the"readingList" permission in the extensionmanifest file:
manifest.json:
{"name":"My reading list extension",..."permissions":["readingList"]}Availability
Chrome features a reading list located on the side panel. It lets users save web pages to read later or when offline.Use the Reading List API to retrieve existing items and add or remove items from the list.
Concepts and usage
Item ordering
Items in the reading list are not in any guaranteed order.
Item uniqueness
Items are keyed by URL. This includes the hash and query string.
Use cases
The following sections demonstrate some common use cases for the Reading List API. SeeExtension samples for complete extension examples.
Add an item
To add an item to the reading list, usechrome.readingList.addEntry():
chrome.readingList.addEntry({title:"New to the web platform in September | web.dev",url:"https://developer.chrome.com/",hasBeenRead:false});Display items
To display items from the reading list, use thechrome.readingList.query() method to retrieve them.method.
constitems=awaitchrome.readingList.query({});for(constitemofitems){// Do something do display the item}Mark an item as read
You can usechrome.readingList.updateEntry() to update the title, URL, and read status. The following code marks an item as read:
chrome.readingList.updateEntry({url:"https://developer.chrome.com/",hasBeenRead:true});Remove an item
To remove an item, usechrome.readingList.removeEntry():
chrome.readingList.removeEntry({url:"https://developer.chrome.com/"});Extension samples
For more Reading List API extensions demos, see theReading List API sample.
Types
AddEntryOptions
Properties
- hasBeenRead
boolean
Will be
trueif the entry has been read. - title
string
The title of the entry.
- url
string
The url of the entry.
QueryInfo
Properties
- hasBeenRead
boolean optional
Indicates whether to search for read (
true) or unread (false) items. - title
string optional
A title to search for.
- url
string optional
A url to search for.
ReadingListEntry
Properties
- creationTime
number
The time the entry was created. Recorded in milliseconds since Jan 1, 1970.
- hasBeenRead
boolean
Will be
trueif the entry has been read. - lastUpdateTime
number
The last time the entry was updated. This value is in milliseconds since Jan 1, 1970.
- title
string
The title of the entry.
- url
string
The url of the entry.
RemoveOptions
Properties
- url
string
The url to remove.
UpdateEntryOptions
Properties
- hasBeenRead
boolean optional
The updated read status. The existing status remains if a value isn't provided.
- title
string optional
The new title. The existing tile remains if a value isn't provided.
- url
string
The url that will be updated.
Methods
addEntry()
chrome.readingList.addEntry(
entry: AddEntryOptions,
): Promise<void>
Adds an entry to the reading list if it does not exist.
Parameters
- entry
The entry to add to the reading list.
Returns
Promise<void>
query()
chrome.readingList.query(
info: QueryInfo,
): Promise<ReadingListEntry[]>
Retrieves all entries that match theQueryInfo properties. Properties that are not provided will not be matched.
Parameters
- info
The properties to search for.
Returns
Promise<ReadingListEntry[]>
removeEntry()
chrome.readingList.removeEntry(
info: RemoveOptions,
): Promise<void>
Removes an entry from the reading list if it exists.
Parameters
- info
The entry to remove from the reading list.
Returns
Promise<void>
updateEntry()
chrome.readingList.updateEntry(
info: UpdateEntryOptions,
): Promise<void>
Updates a reading list entry if it exists.
Parameters
The entry to update.
Returns
Promise<void>
Events
onEntryAdded
chrome.readingList.onEntryAdded.addListener(
callback: function,
)
Triggered when aReadingListEntry is added to the reading list.
Parameters
- callback
function
The
callbackparameter looks like:(entry: ReadingListEntry) => void
- entry
onEntryRemoved
chrome.readingList.onEntryRemoved.addListener(
callback: function,
)
Triggered when aReadingListEntry is removed from the reading list.
Parameters
- callback
function
The
callbackparameter looks like:(entry: ReadingListEntry) => void
- entry
onEntryUpdated
chrome.readingList.onEntryUpdated.addListener(
callback: function,
)
Triggered when aReadingListEntry is updated in the reading list.
Parameters
- callback
function
The
callbackparameter looks like:(entry: ReadingListEntry) => void
- entry
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-11 UTC.