You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.
WARNING: This is the BETA documentation. It may not work with the stable release of Chrome.
WARNING: This is unofficial documentation. It may not work with the current release of Chrome.

Google Chrome Extensions (Labs)

Bookmarks

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

Methods

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

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

Callback function

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

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

get

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

Retrieves the specified BookmarkTreeNode(s).

Parameters

idOrIdList
( string or array of string )
A single string-valued id, or an array of string-valued ids
callback
( function )
Undocumented.

Callback function

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

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

getChildren

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

Retrieves the children of the specified BookmarkTreeNode id.

Parameters

id
( string )
Undocumented.
callback
( function )
Undocumented.

Callback function

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

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

getRecent

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

Retrieves the recently added bookmarks.

Parameters

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

Callback function

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

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

getSubTree

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

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

Callback function

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

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

getTree

chrome.bookmarks.getTree(function callback)

Retrieves the entire Bookmarks hierarchy.

Parameters

callback
( function )
Undocumented.

Callback function

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

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

move

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

Moves the specified BookmarkTreeNode to the provided location.

Parameters

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

Callback function

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

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

remove

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

Removes a bookmark or an empty bookmark folder.

Parameters

id
( string )
Undocumented.
callback
( optional function )
Undocumented.

Callback function

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

function() {...};

removeTree

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

Recursively removes a bookmark folder.

Parameters

id
( string )
Undocumented.
callback
( optional function )
Undocumented.

Callback function

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

function() {...};

search

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

Searches for BookmarkTreeNodes matching the given query.

Parameters

query
( string )
Undocumented.
callback
( function )
Undocumented.

Callback function

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

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

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

id
( string )
Undocumented.
changes
( object )
Undocumented.
title
( optional string )
Undocumented.
url
( optional string )
Undocumented.
callback
( optional function )
Undocumented.

Callback function

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

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

Events

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 )
Undocumented.
changeInfo
( object )
Undocumented.
title
( string )
Undocumented.
url
( optional string )
Undocumented.

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 )
Undocumented.
reorderInfo
( object )
Undocumented.
childIds
( array of string )
Undocumented.

onCreated

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

Fired when a bookmark or folder is created.

Listener parameters

id
( string )
Undocumented.
bookmark
Undocumented.

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.

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 )
Undocumented.
moveInfo
( object )
Undocumented.
parentId
( string )
Undocumented.
index
( integer )
Undocumented.
oldParentId
( string )
Undocumented.
oldIndex
( integer )
Undocumented.

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 )
Undocumented.
removeInfo
( object )
Undocumented.
parentId
( string )
Undocumented.
index
( integer )
Undocumented.

Types

BookmarkTreeNode

( object )
A node (either a bookmark or a folder) in the bookmark tree. Child nodes are ordered within their parent folder.
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 number )
When this node was created, in milliseconds since the epoch (new Date(dateAdded)).
dateGroupModified
( optional number )
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.