Changelog

This release combines three major updates to framer-plugin: the new Navigation API, extended Code File API, and support for Design Pages.

Navigation API

• framer.navigateTo(nodeId, opts?) — Programmatically navigate to canvas nodes, collection items, or code files. Supports optional selection, zoom constraints, and field-level scrolling for collection items. Also available in class instances such as node.navigateTo(), collectionItem.navigateTo(), and codeFile.navigateTo().

Code File API

• framer.subscribeToOpenCodeFile(cb) — Subscribe to the currently open code file, enabling plugins to react when users switch between files.

Design Pages API

Plugins can now read, create, and edit nodes in Design Pages using the same Nodes and Selection APIs you use elsewhere.

• Works with the existing selection and node methods (for example, framer.getSelection() and Node operations)

• Insert and modify frames, text, and images on Design Pages, just like on other pages

• Ideal for plugins that generate explorations, moodboards, or asset grids inside a freeform canvas

Learn more about Design Pages: Design Pages update

This release brings new traits to the Canvas API and plugin development workflow.

Added: Layout Traits

• Added support for layout traits, including stack, grid, padding, and gap.

• Added support for border traits on FrameNode.

• Added support for variant traits on FrameNode.

Added: Code Mode

• Added a new code mode, allowing to open a Plugin in the Code Editor.

This new release introduces brand new APIs for creating menus for your plugin.

Added: Menu APIs

We are introducing new APIs for creating two different types of menu:

• setMenu lets you add a global menu to the plugin window header.

• showContextMenu allows creating context menus anywhere in your plugin.

Added: User APIs

• New User properties: avatarUrl and initials

Improved

• closePlugin now returns never instead of Promise<void>. That means you can treat it like a throw, the code that follows will not be reached. Internally closePlugin throws FramerPluginClosedError, so make sure to ignore it in your exception handlers. framer-plugin stops propagation of unhandled errors and rejections of this class, so you don't need to.

This new release adds support for Gallery fields to CMS APIs, as well as introducing support for managing code components and overrides via the new Code File API.

Added: Code File API

We’ve added several new APIs to help plugin authors manage code files:

• createCodeFile, getCodeFile, and getCodeFiles for creating and retrieving code files

• subscribeToCodeFiles to receive notifications when code files are created or modified

• codeFile.setFileContent, codeFile.rename, and codeFile.remove to update, rename, and delete code files

• codeFile.getVersions to access a file’s version history

Added: Gallery Fields

It is now possible to create and update Gallery fields, as well as set values for them when adding or updating items. This is achieved by the creation of a new "array" field type.

• ManagedCollection.setFields and Collection.addFields support creating Gallery fields.

• ManagedCollection.addItems and Collection.addItems let you add values for Gallery fields.

• CollectionItem.setAttributes can now update Gallery field values.

See our updated CMS guide for more information on working with arrays.

Updated: Collection API

Deprecated Collection and Managed Collection readonly property in favor of managedBy and proper permission-based checks via the Permissions API

Updated: User API

User now has avatarUrl and initials, and is finally documented.

Fixed: Draggable Component

Fixed the <Draggable> component so that the altText parameter is correctly applied when dragging and dropping images, ensuring accessibility metadata isn’t lost.

• Added support for rem units — allowing to set rem units that were announced in our April update

• Added support for Vector Set nodes — these are now exposed for use in plugins

• Improved ManagedCollections API — it’s now possible to call setFields(await getFields()) without running into type errors

This new release introduces APIs for Redirects, which allows to manage your site Redirects programatically. Management can happen in bulk or individually.

• Added addRedirects(), getRedirects(), removeRedirects().

• Added setRedirectOrder() for defining order of Redirects.

• Added Redirect class for specific redirect management.

  
  

This release introduces two entirely new sets of APIs for Plugins: Localization and Permissions. With the new Localization APIs, Plugins are now able to programmatically read and update a site’s Locales and Localization sources.
With the Permissions API, Plugins can check which permissions the Plugin user has (e.g. Design, Content-only) and adapt the Plugin functionality accordingly. Learn how to get started in the Localization Guide and Permission guide.

Note

The framer-plugin package now uses a top-level await, make sure to update vite-framer-plugin to 1.0.7 or higher.

Localization

This release introduces brand new APIs for managing your site's Localizations.

• getLocales lets you get all your site's Locales.

• getDefaultLocale gives you the default Locale.

• getActiveLocale gives you the active Locale.

• getLocalizationGroups retrives all Localization groups and sources.

• setLocalizationData lets you update your site's Localization data.

We have also added Localization support to other existing APIs.

• Collection.getItems now includes Localization data for each item.

• ManagedCollection.addItems lets you include item Localization data.

• Collection.addItems lets you include item Localization data.

• CollectionItem.setAttributes lets you include item Localization data.

Permissions (Preview)

Today, Plugins can only be launched and used by those with full permissions on a Project. A few weeks from now, we’ll allow Plugins to be launched and used by those without design permissions as well. With the Permissions API Preview, we’re giving Plugin authors time to proactively accommodate for this change via these new APIs. Learn more about these flows in the Permissions guide.

• Calling a method unavailable to the user will result in an error.

• isAllowedTo lets you check methods' availability to the user.

• subscribeToIsAllowedTo lets you subscribe to changes in isAllowedTo.

• useIsAllowedTo is a React hook version of subscribeToIsAllowedTo.

CMS

• slugFieldBasedOn is the ID of the field that a Collection's slug is based on.

• Enum Fields can now update, remove, and sort their Enum Cases.

• Fields can now be marked as required during creation.

• Fixed a bug where adding items with HTML content would sometimes error.

• Fixed a bug preventing the referenced Collection of fields being updated.

Canvas

• onDragComplete was added as a callback to the Draggable component.

• preferredImageRendering can now be provided when adding images.

Styles

• Fixed a bug where renaming a Text Style or Color Style would reset its path.

• Text Styles and Color Styles now both expose their full path.
  
  

Plugins version 3.0 enables entirely new functionality within CMS Plugins with a new set of APIs for modifying and adding to existing Collections that weren’t created by your Plugin (known as UnmanagedCollection). Along with this, we’ve made a few changes to the core CMS APIs to add stronger typing and set us up for additional features coming soon.

Breaking Changes

The following CMS functions now require their fieldData to be an object, with value and type properties. Which enforces stronger types across CMS APIs.

• Collection.getFields() now returns Field[].

• BooleanField, StringField, etc. are classes now.

• SupportedCollectionField type has been removed.

• CollectionField type has been removed.

• Collection.getItems() returns typed fieldData.

• CollectionItem.setAttributes() requires typed fieldData.

• ManagedCollection.addItems() requires typed fieldData.

// Before 
managedCollection.addItems([
  { [fieldID]: "Your Value" }
])

// After
managedCollection.addItems([
  { [fieldID]: {
      type: "string",
      value:  "Your Value"
  }
}])

Collections

• Plugins can now write to Collections.

• Added Collection.addItems().

• Added Collection.setItemOrder().

• Added Collection.setFieldOrder().

Collection Fields

• Collection.addFields() lets you create new fields.

• Field.setAttributes() allows you to update the field.

• Field.remove() removes the field from the Collection.

• Collection.removeFields() removes fields in bulk.

The 2.2.0 release brings some updates to the CMS API, with a focus on improving the experience around having multiple Managed Collections created by the same Plugin.

Managed Collections

• Added new ⁠getManagedCollections() method to get all Collections managed by your Plugin.

• Added ⁠setAsActive() method to select the active Collection in the Editor

• Deprecated ⁠getManagedCollection() in favor of ⁠getActiveManagedCollection().

• Fixed a bug where setting Plugin Data on a CollectionItemNode was throwing a Node not found error.

Collections

• Added support for ⁠FieldDivider type in collection fields.

• Added ⁠setAsActive() method to make a collection the active one.

• Added ⁠removeFields() method to remove fields by their ID.

• Added ⁠setFieldOrder() method to arrange fields in a specific order.

• Added ⁠slugFieldName property to Collection interface.

The 2.0 release contains a single breaking change to the id field of the APIs below. Our hashing algorithm for the id had a higher potential for ID collisions than expected. The id field will now be a different hashed value for the same user/project compared to 1.x.x. Logic that stores and compares these values will need updating. To migrate from the old value to the new value, you can reference the apiVersion1Id field.

• getProjectInfo()

• getCurrentUser()

• Resolution support has been added to all image APIs.

• Collection item draft status is now exposed in the API.

• Plugin windows now support maximum width/height.

Plugins initial public release.