paramName
( optional Type array of paramType )
Undocumented.
Description of this parameter from the json schema.
Bookmarks

Use the chrome.bookmarks module to create, organize, and otherwise manipulate bookmarks.

Manifest

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

{
  "name": "My extension that uses bookmarks",
  "version": "0.1",
  "permissions": [
    "bookmarks"
  ],
  ...
}

Objects and properties

Bookmarks are organized in a tree, where each node in the tree is either a bookmark or a group (a folder that can contain nodes). 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.

[PENDING: Update and introduce the following image or delete the file.]

2 kinds of bookmark objects

[PENDING: The following section needs to be updated or deleted.]

Say you have bookmark hierarchy that looks like this:

  • Bookmarks
    • Google
      • Apps
        • ...
        • ...
        • ...
      • Google homepage
    • Example

Here's how those bookmarks might be represented with bookmark objects:

a hierarchy of bookmarks

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 a full example of using bookmarks, see the bookmarks sample.

API reference: chrome.bookmarks

Methods

create

void 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

bookmark
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
parentId
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
index
( optional Type array of integer )
Undocumented.
Description of this parameter from the json schema.
title
( optional Type array of string )
Undocumented.
Description of this parameter from the json schema.
url
( optional Type array of string )
Undocumented.
Description of this parameter from the json schema.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

function(BookmarkTreeNode result) {...});
result
( BookmarkTreeNode array of paramType )
Undocumented.
Description of this parameter from the json schema.

get

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

Retrieves the specified BookmarkTreeNode(s).

Parameters

idOrIdList
( Type array of string or array of string )
A single string-valued id, or an array of string-valued ids
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

function(array of BookmarkTreeNode results) {...});
results
( Type array of BookmarkTreeNode array of paramType paramType )
Undocumented.
Description of this parameter from the json schema.

getChildren

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

Retrieves the children of the specified BookmarkTreeNode id.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

function(array of BookmarkTreeNode results) {...});
results
( Type array of BookmarkTreeNode array of paramType paramType )
Undocumented.
Description of this parameter from the json schema.

getTree

void chrome.bookmarks.getTree(, function callback)

Retrieves the entire Bookmarks hierarchy.

Parameters

callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

function(array of BookmarkTreeNode results) {...});
results
( Type array of BookmarkTreeNode array of paramType paramType )
Undocumented.
Description of this parameter from the json schema.

move

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

Moves the specified BookmarkTreeNode to the provided location.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
destination
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
parentId
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
index
( optional Type array of integer )
Undocumented.
Description of this parameter from the json schema.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

function(BookmarkTreeNode result) {...});
result
( BookmarkTreeNode array of paramType )
Undocumented.
Description of this parameter from the json schema.

remove

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

Removes a bookmark or an empty bookmark folder.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

function() {...});

removeTree

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

Recursively removes a bookmark folder.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

function() {...});

search

void chrome.bookmarks.search(, string query, function callback)

Seaches for BookmarkTreeNodes matching the given query.

Parameters

query
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

function(array of BookmarkTreeNode results) {...});
results
( Type array of BookmarkTreeNode array of paramType paramType )
Undocumented.
Description of this parameter from the json schema.

update

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

Updates the properties of a bookmark or folder. Only specify the properties that you want to change, unspecified properties will be left unchanged. NOTE: currently, only 'title' is supported.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
changes
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
title
( optional Type array of string )
Undocumented.
Description of this parameter from the json schema.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

function(BookmarkTreeNode result) {...});
result
( BookmarkTreeNode array of paramType )
Undocumented.
Description of this parameter from the json schema.

Events

onChanged

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

Fired when a bookmark or folder changes. NOTE: currently, only title changes trigger this.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
changeInfo
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
title
( Type array of string )
Undocumented.
Description of this parameter from the json schema.

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

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
reorderInfo
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
childIds
( Type array of Type array of string paramType )
Undocumented.
Description of this parameter from the json schema.

onCreated

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

Fired when a bookmark or folder is created.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
bookmark
( BookmarkTreeNode array of paramType )
Undocumented.
Description of this parameter from the json schema.

onMoved

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

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

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
moveInfo
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
parentId
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
index
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
oldParentId
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
oldIndex
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.

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.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
removeInfo
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
parentId
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
index
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.

Types

BookmarkTreeNode

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