chrome.bookmarks

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.
Availability: Since Chrome 35.
Permissions: "bookmarks"
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 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.

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.

Summary

Types
BookmarkTreeNodeUnmodifiable
BookmarkTreeNode
Properties
MAX_WRITE_OPERATIONS_PER_HOUR
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
Methods
get − chrome.bookmarks.get(string or array of string idOrIdList, function callback)
getChildren − chrome.bookmarks.getChildren(string id, function callback)
getRecent − chrome.bookmarks.getRecent(integer numberOfItems, function callback)
getTree − chrome.bookmarks.getTree(function callback)
getSubTree − chrome.bookmarks.getSubTree(string id, function callback)
search − chrome.bookmarks.search(string or object query, function callback)
create − chrome.bookmarks.create(object bookmark, function callback)
move − chrome.bookmarks.move(string id, object destination, function callback)
update − chrome.bookmarks.update(string id, object changes, function callback)
remove − chrome.bookmarks.remove(string id, function callback)
removeTree − chrome.bookmarks.removeTree(string id, function callback)
Events
onCreated
onRemoved
onChanged
onMoved
onChildrenReordered
onImportBegan
onImportEnded

Types

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).
Enum
"managed"

BookmarkTreeNode

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

The unique identifier for the node. IDs are unique within the current profile, and they remain valid even after the browser is restarted.

string (optional) parentId

The id of the parent folder. Omitted for the root node.

integer (optional) index

The 0-based position of this node within its parent folder.

string (optional) url

The URL navigated to when a user clicks the bookmark. Omitted for folders.

string title

The text displayed for the node.

double (optional) dateAdded

When this node was created, in milliseconds since the epoch (new Date(dateAdded)).

double (optional) dateGroupModified

When the contents of this folder last changed, in milliseconds since the epoch.

BookmarkTreeNodeUnmodifiable (optional) unmodifiable

Since Chrome 37.

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

array of BookmarkTreeNode (optional) children

An ordered list of children of this node.

Properties

1,000,000 chrome.bookmarks.MAX_WRITE_OPERATIONS_PER_HOUR

Deprecated since Chrome 38. Bookmark write operations are no longer limited by Chrome.

1,000,000 chrome.bookmarks.MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Deprecated since Chrome 38. Bookmark write operations are no longer limited by Chrome.

Methods

get

chrome.bookmarks.get(string or array of string idOrIdList, function callback)

Retrieves the specified BookmarkTreeNode(s).

Parameters
string or array of string idOrIdList

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

function callback

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

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

getChildren

chrome.bookmarks.getChildren(string id, function callback)

Retrieves the children of the specified BookmarkTreeNode id.

Parameters
string id
function callback

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

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

getRecent

chrome.bookmarks.getRecent(integer numberOfItems, function callback)

Retrieves the recently added bookmarks.

Parameters
integer numberOfItems

The maximum number of items to return.

function callback

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

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

getTree

chrome.bookmarks.getTree(function callback)

Retrieves the entire Bookmarks hierarchy.

Parameters
function callback

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

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

getSubTree

chrome.bookmarks.getSubTree(string id, function callback)

Retrieves part of the Bookmarks hierarchy, starting at the specified node.

Parameters
string id

The ID of the root of the subtree to retrieve.

function callback

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

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

Searches for BookmarkTreeNodes matching the given query. Queries specified with an object produce BookmarkTreeNodes matching all specified properties.

Parameters
string or object query

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, and title may be specified and bookmarks matching all specified properties will be produced.

function callback

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

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

create

chrome.bookmarks.create(object bookmark, function callback)

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

Parameters
object bookmark
string (optional) parentId

Defaults to the Other Bookmarks folder.

integer (optional) index
string (optional) title
string (optional) url
function (optional) callback

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

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

move

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

Moves the specified BookmarkTreeNode to the provided location.

Parameters
string id
object destination
string (optional) parentId
integer (optional) index
function (optional) callback

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

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

update

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

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
string id
object changes
string (optional) title
string (optional) url
function (optional) callback

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

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

remove

chrome.bookmarks.remove(string id, function callback)

Removes a bookmark or an empty bookmark folder.

Parameters
string id
function (optional) callback

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

function() {...};

removeTree

chrome.bookmarks.removeTree(string id, function callback)

Recursively removes a bookmark folder.

Parameters
string id
function (optional) callback

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

function() {...};

Events

onCreated

Fired when a bookmark or folder is created.

addListener

chrome.bookmarks.onCreated.addListener(function callback)
Parameters
function callback

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

function(string id, BookmarkTreeNode bookmark) {...};
string id
BookmarkTreeNode bookmark

onRemoved

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.

addListener

chrome.bookmarks.onRemoved.addListener(function callback)
Parameters
function callback

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

function(string id, object removeInfo) {...};
string id
object removeInfo
string parentId
integer index
BookmarkTreeNode node

Since Chrome 48.

onChanged

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

addListener

chrome.bookmarks.onChanged.addListener(function callback)
Parameters
function callback

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

function(string id, object changeInfo) {...};
string id
object changeInfo
string title
string (optional) url

onMoved

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

addListener

chrome.bookmarks.onMoved.addListener(function callback)
Parameters
function callback

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

function(string id, object moveInfo) {...};
string id
object moveInfo
string parentId
integer index
string oldParentId
integer oldIndex

onChildrenReordered

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

addListener

chrome.bookmarks.onChildrenReordered.addListener(function callback)
Parameters
function callback

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

function(string id, object reorderInfo) {...};
string id
object reorderInfo
array of string childIds

onImportBegan

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.

addListener

chrome.bookmarks.onImportBegan.addListener(function callback)
Parameters
function callback

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

function() {...};

onImportEnded

Fired when a bookmark import session is ended.

addListener

chrome.bookmarks.onImportEnded.addListener(function callback)
Parameters
function callback

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

function() {...};