Description
Use the chrome.bookmarks
API to create, organize, and otherwise manipulate bookmarks. Also see Override Pages, which you can use to create a custom Bookmark Manager page.
![Clicking the star adds a bookmark](/https/developer.chrome.com/static/docs/extensions/reference/api/images/bookmarks.png)
Permissions
bookmarks
You must declare the "bookmarks" permission in the extension manifest to use the bookmarks API. For example:
{
"name": "My extension",
...
"permissions": [
"bookmarks"
],
...
}
Concepts and usage
Objects and properties
Bookmarks are organized in a tree, where each node in the tree is either a bookmark or a folder (sometimes called a group). Each node in the tree is represented by a bookmarks.BookmarkTreeNode object.
BookmarkTreeNode
properties are used throughout the chrome.bookmarks
API. For example, when you
call bookmarks.create, you pass in the new node's parent (parentId
), and, optionally, the
node's index
, title
, and url
properties. See bookmarks.BookmarkTreeNode for information
about the properties a node can have.
Examples
The following code creates a folder with the title "Extension bookmarks". The first argument to
create()
specifies properties for the new folder. The second argument defines a function to be
executed after the folder is created.
chrome.bookmarks.create(
{'parentId': bookmarkBar.id, 'title': 'Extension bookmarks'},
function(newFolder) {
console.log("added folder: " + newFolder.title);
},
);
The next snippet creates a bookmark pointing to the developer documentation for extensions. Since nothing bad will happen if creating the bookmark fails, this code doesn't bother to define a callback function.
chrome.bookmarks.create({
'parentId': extensionsFolderId,
'title': 'Extensions doc',
'url': 'https://developer.chrome.com/docs/extensions',
});
To try this API, install the Bookmarks API example from the chrome-extension-samples repository.
Types
BookmarkTreeNode
A node (either a bookmark or a folder) in the bookmark tree. Child nodes are ordered within their parent folder.
Properties
-
children
BookmarkTreeNode[] optional
An ordered list of children of this node.
-
dateAdded
number optional
When this node was created, in milliseconds since the epoch (
new Date(dateAdded)
). -
dateGroupModified
number optional
When the contents of this folder last changed, in milliseconds since the epoch.
-
dateLastUsed
number optional
Chrome 114+When this node was last opened, in milliseconds since the epoch. Not set for folders.
-
id
string
The unique identifier for the node. IDs are unique within the current profile, and they remain valid even after the browser is restarted.
-
index
number optional
The 0-based position of this node within its parent folder.
-
parentId
string optional
The
id
of the parent folder. Omitted for the root node. -
title
string
The text displayed for the node.
-
unmodifiable
"managed"
optionalIndicates the reason why this node is unmodifiable. The
managed
value indicates that this node was configured by the system administrator or by the custodian of a supervised user. Omitted if the node can be modified by the user and the extension (default). -
url
string optional
The URL navigated to when a user clicks the bookmark. Omitted for folders.
BookmarkTreeNodeUnmodifiable
Indicates the reason why this node is unmodifiable. The managed
value indicates that this node was configured by the system administrator. Omitted if the node can be modified by the user and the extension (default).
Value
"managed"
CreateDetails
Object passed to the create() function.
Properties
-
index
number optional
-
parentId
string optional
Defaults to the Other Bookmarks folder.
-
title
string optional
-
url
string optional
Properties
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
Bookmark write operations are no longer limited by Chrome.
Value
1000000
MAX_WRITE_OPERATIONS_PER_HOUR
Bookmark write operations are no longer limited by Chrome.
Value
1000000
Methods
create()
chrome.bookmarks.create(
bookmark: CreateDetails,
callback?: function,
)
Creates a bookmark or folder under the specified parentId. If url is NULL or missing, it will be a folder.
Parameters
-
bookmark
-
callback
function optional
The
callback
parameter looks like:(result: BookmarkTreeNode) => void
-
result
-
Returns
-
Promise<BookmarkTreeNode>
Chrome 90+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
get()
chrome.bookmarks.get(
idOrIdList: string | [string, ...string[]],
callback?: function,
)
Retrieves the specified BookmarkTreeNode(s).
Parameters
-
idOrIdList
string | [string, ...string[]]
A single string-valued id, or an array of string-valued ids
-
callback
function optional
The
callback
parameter looks like:(results: BookmarkTreeNode[]) => void
-
results
-
Returns
-
Promise<BookmarkTreeNode[]>
Chrome 90+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getChildren()
chrome.bookmarks.getChildren(
id: string,
callback?: function,
)
Retrieves the children of the specified BookmarkTreeNode id.
Parameters
-
id
string
-
callback
function optional
The
callback
parameter looks like:(results: BookmarkTreeNode[]) => void
-
results
-
Returns
-
Promise<BookmarkTreeNode[]>
Chrome 90+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getRecent()
chrome.bookmarks.getRecent(
numberOfItems: number,
callback?: function,
)
Retrieves the recently added bookmarks.
Parameters
-
numberOfItems
number
The maximum number of items to return.
-
callback
function optional
The
callback
parameter looks like:(results: BookmarkTreeNode[]) => void
-
results
-
Returns
-
Promise<BookmarkTreeNode[]>
Chrome 90+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getSubTree()
chrome.bookmarks.getSubTree(
id: string,
callback?: function,
)
Retrieves part of the Bookmarks hierarchy, starting at the specified node.
Parameters
-
id
string
The ID of the root of the subtree to retrieve.
-
callback
function optional
The
callback
parameter looks like:(results: BookmarkTreeNode[]) => void
-
results
-
Returns
-
Promise<BookmarkTreeNode[]>
Chrome 90+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getTree()
chrome.bookmarks.getTree(
callback?: function,
)
Retrieves the entire Bookmarks hierarchy.
Parameters
-
callback
function optional
The
callback
parameter looks like:(results: BookmarkTreeNode[]) => void
-
results
-
Returns
-
Promise<BookmarkTreeNode[]>
Chrome 90+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
move()
chrome.bookmarks.move(
id: string,
destination: object,
callback?: function,
)
Moves the specified BookmarkTreeNode to the provided location.
Parameters
-
id
string
-
destination
object
-
index
number optional
-
parentId
string optional
-
-
callback
function optional
The
callback
parameter looks like:(result: BookmarkTreeNode) => void
-
result
-
Returns
-
Promise<BookmarkTreeNode>
Chrome 90+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
remove()
chrome.bookmarks.remove(
id: string,
callback?: function,
)
Removes a bookmark or an empty bookmark folder.
Parameters
-
id
string
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 90+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
removeTree()
chrome.bookmarks.removeTree(
id: string,
callback?: function,
)
Recursively removes a bookmark folder.
Parameters
-
id
string
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 90+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
search()
chrome.bookmarks.search(
query: string | object,
callback?: function,
)
Searches for BookmarkTreeNodes matching the given query. Queries specified with an object produce BookmarkTreeNodes matching all specified properties.
Parameters
-
query
string | object
Either a string of words and quoted phrases that are matched against bookmark URLs and titles, or an object. If an object, the properties
query
,url
, andtitle
may be specified and bookmarks matching all specified properties will be produced.-
query
string optional
A string of words and quoted phrases that are matched against bookmark URLs and titles.
-
title
string optional
The title of the bookmark; matches verbatim.
-
url
string optional
The URL of the bookmark; matches verbatim. Note that folders have no URL.
-
-
callback
function optional
The
callback
parameter looks like:(results: BookmarkTreeNode[]) => void
-
results
-
Returns
-
Promise<BookmarkTreeNode[]>
Chrome 90+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
update()
chrome.bookmarks.update(
id: string,
changes: object,
callback?: function,
)
Updates the properties of a bookmark or folder. Specify only the properties that you want to change; unspecified properties will be left unchanged. Note: Currently, only 'title' and 'url' are supported.
Parameters
-
id
string
-
changes
object
-
title
string optional
-
url
string optional
-
-
callback
function optional
The
callback
parameter looks like:(result: BookmarkTreeNode) => void
-
result
-
Returns
-
Promise<BookmarkTreeNode>
Chrome 90+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
Events
onChanged
chrome.bookmarks.onChanged.addListener(
callback: function,
)
Fired when a bookmark or folder changes. Note: Currently, only title and url changes trigger this.
Parameters
-
callback
function
The
callback
parameter looks like:(id: string, changeInfo: object) => void
-
id
string
-
changeInfo
object
-
title
string
-
url
string optional
-
-
onChildrenReordered
chrome.bookmarks.onChildrenReordered.addListener(
callback: function,
)
Fired when the children of a folder have changed their order due to the order being sorted in the UI. This is not called as a result of a move().
Parameters
-
callback
function
The
callback
parameter looks like:(id: string, reorderInfo: object) => void
-
id
string
-
reorderInfo
object
-
childIds
string[]
-
-
onCreated
chrome.bookmarks.onCreated.addListener(
callback: function,
)
Fired when a bookmark or folder is created.
Parameters
-
callback
function
The
callback
parameter looks like:(id: string, bookmark: BookmarkTreeNode) => void
-
id
string
-
bookmark
-
onImportBegan
chrome.bookmarks.onImportBegan.addListener(
callback: function,
)
Fired when a bookmark import session is begun. Expensive observers should ignore onCreated updates until onImportEnded is fired. Observers should still handle other notifications immediately.
Parameters
-
callback
function
The
callback
parameter looks like:() => void
onImportEnded
chrome.bookmarks.onImportEnded.addListener(
callback: function,
)
Fired when a bookmark import session is ended.
Parameters
-
callback
function
The
callback
parameter looks like:() => void
onMoved
chrome.bookmarks.onMoved.addListener(
callback: function,
)
Fired when a bookmark or folder is moved to a different parent folder.
Parameters
-
callback
function
The
callback
parameter looks like:(id: string, moveInfo: object) => void
-
id
string
-
moveInfo
object
-
index
number
-
oldIndex
number
-
oldParentId
string
-
parentId
string
-
-
onRemoved
chrome.bookmarks.onRemoved.addListener(
callback: function,
)
Fired when a bookmark or folder is removed. When a folder is removed recursively, a single notification is fired for the folder, and none for its contents.
Parameters
-
callback
function
The
callback
parameter looks like:(id: string, removeInfo: object) => void
-
id
string
-
removeInfo
object
-
index
number
-
nodeChrome 48+
-
parentId
string
-
-