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.
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
BookmarkTreeNode
CreateDetails
BookmarkTreeNodeUnmodifiable
Properties
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
MAX_WRITE_OPERATIONS_PER_HOUR
Methods
create
chrome.bookmarks.create(bookmark: CreateDetails, callback: function)
get
chrome.bookmarks.get(idOrIdList: string | string[], callback: function)
getChildren
chrome.bookmarks.getChildren(id: string, callback: function)
getRecent
chrome.bookmarks.getRecent(numberOfItems: number, callback: function)
getSubTree
chrome.bookmarks.getSubTree(id: string, callback: function)
getTree
chrome.bookmarks.getTree(callback: function)
move
chrome.bookmarks.move(id: string, destination: object, callback: function)
remove
chrome.bookmarks.remove(id: string, callback: function)
removeTree
chrome.bookmarks.removeTree(id: string, callback: function)
search
chrome.bookmarks.search(query: string | object, callback: function)
update
chrome.bookmarks.update(id: string, changes: object, callback: function)
Events
onChanged
onChildrenReordered
onCreated
onImportBegan
onImportEnded
onMoved
onRemoved

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.
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
BookmarkTreeNodeUnmodifiable optional
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).
url
string optional
The URL navigated to when a user clicks the bookmark. Omitted for folders.

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

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"

Properties

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

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

Value

number 1000000

MAX_WRITE_OPERATIONS_PER_HOUR

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

Value

number 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
CreateDetails
callback
function
The callback parameter should be a function that looks like this:
(result: BookmarkTreeNode) => {...}
- result
  BookmarkTreeNode

get

chrome.bookmarks.get(idOrIdList: string | string[], callback: function)

Retrieves the specified BookmarkTreeNode(s).

Parameters

idOrIdList
string | string[]
A single string-valued id, or an array of string-valued ids
callback
function
The callback parameter should be a function that looks like this:
(results: BookmarkTreeNode[]) => {...}
- results
  BookmarkTreeNode[]

getChildren

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

Retrieves the children of the specified BookmarkTreeNode id.

Parameters

id
string
callback
function
The callback parameter should be a function that looks like this:
(results: BookmarkTreeNode[]) => {...}
- results
  BookmarkTreeNode[]

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
The callback parameter should be a function that looks like this:
(results: BookmarkTreeNode[]) => {...}
- results
  BookmarkTreeNode[]

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
The callback parameter should be a function that looks like this:
(results: BookmarkTreeNode[]) => {...}
- results
  BookmarkTreeNode[]

getTree

chrome.bookmarks.getTree(callback: function)

Retrieves the entire Bookmarks hierarchy.

Parameters

callback
function
The callback parameter should be a function that looks like this:
(results: BookmarkTreeNode[]) => {...}
- results
  BookmarkTreeNode[]

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
The callback parameter should be a function that looks like this:
(result: BookmarkTreeNode) => {...}
- result
  BookmarkTreeNode

remove

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

Removes a bookmark or an empty bookmark folder.

Parameters

id
string
callback
function
The callback parameter should be a function that looks like this:
() => {...}

removeTree

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

Recursively removes a bookmark folder.

Parameters

id
string
callback
function
The callback parameter should be a function that looks like this:
() => {...}

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, and title may be specified and bookmarks matching all specified properties will be produced.
callback
function
The callback parameter should be a function that looks like this:
(results: BookmarkTreeNode[]) => {...}
- results
  BookmarkTreeNode[]

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
The callback parameter should be a function that looks like this:
(result: BookmarkTreeNode) => {...}
- result
  BookmarkTreeNode

Events

onChanged

chrome.bookmarks.onChanged.addListener(listener: function)

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

Event

listener
function
The listener parameter should be a function that looks like this:
(id: string, changeInfo: object) => {...}
- id
  string
- changeInfo
  object
  title
  string
  url
  string optional

onChildrenReordered

chrome.bookmarks.onChildrenReordered.addListener(listener: 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().

Event

listener
function
The listener parameter should be a function that looks like this:
(id: string, reorderInfo: object) => {...}
- id
  string
- reorderInfo
  object
  childIds
  string[]

onCreated

chrome.bookmarks.onCreated.addListener(listener: function)

Fired when a bookmark or folder is created.

Event

listener
function
The listener parameter should be a function that looks like this:
(id: string, bookmark: BookmarkTreeNode) => {...}
- id
  string
- bookmark
  BookmarkTreeNode

onImportBegan

chrome.bookmarks.onImportBegan.addListener(listener: 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.

Event

listener
function
The listener parameter should be a function that looks like this:
() => {...}

onImportEnded

chrome.bookmarks.onImportEnded.addListener(listener: function)

Fired when a bookmark import session is ended.

Event

listener
function
The listener parameter should be a function that looks like this:
() => {...}

onMoved

chrome.bookmarks.onMoved.addListener(listener: function)

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

Event

listener
function
The listener parameter should be a function that looks like this:
(id: string, moveInfo: object) => {...}
- id
  string
- moveInfo
  object
  index
  number
  oldIndex
  number
  oldParentId
  string
  parentId
  string

onRemoved

chrome.bookmarks.onRemoved.addListener(listener: 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.

Event

listener
function
The listener parameter should be a function that looks like this:
(id: string, removeInfo: object) => {...}
- id
  string
- removeInfo
  object
  index
  number
  node
  BookmarkTreeNode
  parentId
  string