Google Chrome Extensions

chrome.bookmarks

Use the chrome.bookmarks module 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

Manifest

You must declare the "bookmarks" permission in the extension manifest to use the bookmarks API. For example:

{
  "name": "My extension",
  ...
  "permissions": [
    "bookmarks"
  ],
  ...
}

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 BookmarkTreeNode object.

BookmarkTreeNode properties are used throughout the chrome.bookmarks API. For example, when you call create(), you pass in the new node's parent (parentId), and, optionally, the node's index, title, and url properties. See BookmarkTreeNode for information about the properties a node can have.

Note: You cannot use this API to add or remove entries in the root folder. You also cannot rename, move, or remove the special "Bookmarks Bar" and "Other Bookmarks" folders.

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': 'http://code.google.com/chrome/extensions'});

For an example of using this API, see the basic bookmarks sample. For other examples and for help in viewing the source code, see Samples.

API Reference: chrome.bookmarks

Types

BookmarkTreeNode

( object )
A node (either a bookmark or a folder) in the bookmark tree. Child nodes are ordered within their parent folder.

Properties of BookmarkTreeNode

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.
parentId ( optional string )
The id of the parent folder. Omitted for the root node.
index ( optional integer )
The 0-based position of this node within its parent folder.
url ( optional string )
The URL navigated to when a user clicks the bookmark. Omitted for folders.
title ( string )
The text displayed for the node.
dateAdded ( optional double )
When this node was created, in milliseconds since the epoch (new Date(dateAdded)).
dateGroupModified ( optional double )
When the contents of this folder last changed, in milliseconds since the epoch.
children ( optional array of BookmarkTreeNode )
An ordered list of children of this node.

Properties

MAX_WRITE_OPERATIONS_PER_HOUR

chrome.bookmarks.MAX_WRITE_OPERATIONS_PER_HOUR
MAX_WRITE_OPERATIONS_PER_HOUR ( 100 )
The maximum number of move, update, create, or remove operations that can be performed each hour. Updates that would cause this limit to be exceeded fail.

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

chrome.bookmarks.MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE ( 2 )
The maximum number of move, update, create, or remove operations that can be performed each minute, sustained over 10 minutes. Updates that would cause this limit to be exceeded fail.

Methods

get

chrome.bookmarks.get(array of string or string idOrIdList)

Retrieves the specified BookmarkTreeNode(s).

Parameters

idOrIdList ( array of string or string )
A single string-valued id, or an array of string-valued ids

Callback function

The callback parameter should specify a function that looks like this:

function(array of BookmarkTreeNode results) {...};
results ( array of BookmarkTreeNode )

getChildren

chrome.bookmarks.getChildren(string id)

Retrieves the children of the specified BookmarkTreeNode id.

Parameters

id ( string )

Callback function

The callback parameter should specify a function that looks like this:

function(array of BookmarkTreeNode results) {...};
results ( array of BookmarkTreeNode )

getRecent

chrome.bookmarks.getRecent(integer numberOfItems)

Retrieves the recently added bookmarks.

Parameters

numberOfItems ( integer )
The maximum number of items to return.

Callback function

The callback parameter should specify a function that looks like this:

function(array of BookmarkTreeNode results) {...};
results ( array of BookmarkTreeNode )

getTree

chrome.bookmarks.getTree()

Retrieves the entire Bookmarks hierarchy.

getSubTree

chrome.bookmarks.getSubTree(string id)

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

The callback parameter should specify a function that looks like this:

function(array of BookmarkTreeNode results) {...};
results ( array of BookmarkTreeNode )
chrome.bookmarks.search(string query)

Searches for BookmarkTreeNodes matching the given query.

Parameters

query ( string )

Callback function

The callback parameter should specify a function that looks like this:

function(array of BookmarkTreeNode results) {...};
results ( array of BookmarkTreeNode )

create

chrome.bookmarks.create(object bookmark)

Creates a bookmark or folder under the specified parentId. If url is NULL or missing, it will be a folder.

Parameters

bookmark ( object )
parentId ( optional string )
Defaults to the Other Bookmarks folder.
index ( optional integer )
title ( optional string )
url ( optional string )

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function(BookmarkTreeNode result) {...};
result ( BookmarkTreeNode )

move

chrome.bookmarks.move(string id, object destination)

Moves the specified BookmarkTreeNode to the provided location.

Parameters

id ( string )
destination ( object )
parentId ( optional string )
index ( optional integer )

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function(BookmarkTreeNode result) {...};
result ( BookmarkTreeNode )

update

chrome.bookmarks.update(string id, object changes)

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 ( optional string )
url ( optional string )

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function(BookmarkTreeNode result) {...};
result ( BookmarkTreeNode )

remove

chrome.bookmarks.remove(string id)

Removes a bookmark or an empty bookmark folder.

Parameters

id ( string )

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function() {...};

removeTree

chrome.bookmarks.removeTree(string id)

Recursively removes a bookmark folder.

Parameters

id ( string )

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function() {...};

Events

onCreated

chrome.bookmarks.onCreated.addListener(function(string id, BookmarkTreeNode bookmark) {...});

Fired when a bookmark or folder is created.

Listener Parameters

id ( string )
bookmark ( BookmarkTreeNode )

onRemoved

chrome.bookmarks.onRemoved.addListener(function(string id, object removeInfo) {...});

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.

Listener Parameters

id ( string )
removeInfo ( object )
parentId ( string )
index ( integer )

onChanged

chrome.bookmarks.onChanged.addListener(function(string id, object changeInfo) {...});

Fired when a bookmark or folder changes. Note: Currently, only title and url changes trigger this.

Listener Parameters

id ( string )
changeInfo ( object )
title ( string )
url ( optional string )

onMoved

chrome.bookmarks.onMoved.addListener(function(string id, object moveInfo) {...});

Fired when a bookmark or folder is moved to a different parent folder.

Listener Parameters

id ( string )
moveInfo ( object )
parentId ( string )
index ( integer )
oldParentId ( string )
oldIndex ( integer )

onChildrenReordered

chrome.bookmarks.onChildrenReordered.addListener(function(string id, object reorderInfo) {...});

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().

Listener Parameters

id ( string )
reorderInfo ( object )
childIds ( array of string )

onImportBegan

chrome.bookmarks.onImportBegan.addListener(function() {...});

Fired when a bookmark import session is begun. Expensive observers should ignore handleCreated updates until onImportEnded is fired. Observers should still handle other notifications immediately.

onImportEnded

chrome.bookmarks.onImportEnded.addListener(function() {...});

Fired when a bookmark import session is ended.

Sample Extensions that use chrome.bookmarks

  • My Bookmarks – A browser action with a popup dump of all bookmarks, including search, add, edit and delete.
  • Event Page Example – Demonstrates usage and features of the event page
  • Chrome Sounds – Enjoy a more magical and immersive experience when browsing the web using the power of sound.