Update your extensions ahead of upcoming bookmark sync changes

James Lee
James Lee

Published: June 17, 2025

Last August, we announced upcoming changes to the Chrome identity model on Windows, Mac, and Linux platforms, following those which have already been launched on iOS and Android. The goal of these changes is to align Chrome with current user expectations regarding signing in. Users increasingly expect to just sign in to get access to their stuff, including bookmarks, and sign out to keep it safe.

As part of rolling out these updates, we're introducing changes to how Chrome stores bookmarks on desktop. Bookmarks, for example, that are stored locally on a device will remain local upon sign-in; users can optionally choose to upload such data to their Google Account individually or in bulk. To allow extensions to support these, we are exposing new data on the Chrome Extensions API. The following information is relevant to any authors of Chrome Extensions that use the chrome.bookmarks API.

Overview

Today, users always have a single set of top-level folders, including the "Bookmarks bar" and "Other bookmarks" folders. The data in these folders may or may not be synced depending on if the user is signed in with syncing enabled or not.

As part of the identity model changes, Chrome will separate syncing and non-syncing bookmarks into two separate subtrees in the bookmarks tree. In some cases where a user has not chosen to upload all of their bookmarks to their account, a user may have both syncing and non-syncing bookmark folders simultaneously. Extensions which use the bookmarks API may need updating, in order to display the bookmarks tree in a way that is clear to users.

Detailed API changes

For users with a mixture of syncing and non-syncing bookmarks, the bookmarks API may return a tree similar to the following on the getTree API:

  • id=A (name: "Bookmarks bar", folderType: "bookmarks-bar", syncing: true)
    • …
  • id=B (name: "Other bookmarks", folderType: "other", syncing: true)
    • …
  • id=C (name: "Bookmarks bar", folderType: "bookmarks-bar", syncing: false)
    • …
  • id=D (name: "Other bookmarks", folderType: "other", syncing: false)
    • …

To let extension developers distinguish between these top-level folders, two new properties have been added to the API:

  • folderType: this allows extensions to identify the "special" folders such as the bookmarks bar. Note that the name and id shouldn't be used for this purpose (name is locale-dependent, and id is not fixed)
  • syncing: to allow extensions to differentiate between the syncing and non-syncing parts of the tree. This will be true before the identity model changes if the user is signed in and has sync enabled.

Extension updates

If any of the following things are true for your extension, you may need to make updates:

  • If your extension displays the full result of getTree to the user to prevent identically-named versions of, for example, the bookmarks bar from being displayed. You may want to append a suffix to the name, or provide some other UI treatment.
  • If your extension attempts to match the bookmarks-bar, other, or mobile permanent folders by id or name. These methods were already unsupported.
  • If your extension assumes that there is exactly or at most one instance of the bookmarks-bar, other, or mobile permanent folders

Testing

The new folderType and syncing extension API properties are documented and available in the latest Chrome Canary release (version 138.0.7196.0 or later).

Users in stable Chrome channels have a single storage (that is, at most one of each of the folder types). For testing purposes you can enable dual storages as follows:

  1. Enable both the following in chrome://flags, and restart Chrome
    • sync-enable-bookmarks-in-transport-mode
    • enable-bookmarks-selected-type-on-signin-for-testing
  2. Add a new Chrome profile (https://support.google.com/chrome/answer/2364824)
    • Don't sign in: choose "Continue without an account".
  3. If you bookmark pages, they will be added to the non-syncing storage.
  4. Now sign in to Chrome:
    • Click that avatar picture at the top-right, next to the three-dot menu.
    • Click "Sign in to Chrome" and follow the prompts.
    • Choose "No thanks" when asked if you want to turn on sync.
  5. If you bookmark pages, they will be added to the syncing storage (enabling you to test the dual-storage case).

Timelines

The changes to expose dual storages will be rolled out gradually, and will start rolling out for a subset of Chrome Stable channel users not before end-June 2025, starting for a small percentage of users and then rolling out more widely over the following weeks.