Search

API Reference

A list of all functions and attributes available on the framer Plugin API.

CMS APIs

Framer provides APIs to interact with our CMS. Collections can be either user-created (Unmanaged) or controlled by a Plugin (Managed). The Collection types share similar API structures and Plugin authors can choose which Collection type works best for their use-case. Reference the latest APIs below or learn more with the CMS guide.

getActiveCollection

()

Retrieve the Collection currently active (selected) in the Framer UI.

getActiveManagedCollection

()

Retrieve the currently active managed Collection from the UI.

getCollections

()

Get all Collections in the project. Both Managed and Unmanaged.

getManagedCollections

()

Retrieve Collections that are managed by the current Plugin.

Collection

A Collection that is not controlled by a Plugin.

addFields

()

Create new unmanaged Collection fields.

addItems

()

Add new Items to a Collection.

getFields

()

Fetch all Fields in a Collection.

getItems

()

Retrieve all Items within a Collection.

readonly

Whether a Collection is read-only.

removeFields

()

Remove fields from a Collection by their IDs.

removeItems

()

Remove Items from a Collection by their IDs.

setAsActive

()

Set the Collection as active.

setFieldOrder

()

Reorder the Fields in a Collection based on an array of Field IDs.

setItemOrder

()

Reorder the Items in a Collection based on an array of Item IDs.

slugFieldBasedOn

The ID of the Field the slug is based on.

slugFieldName

The name of the Field used as the slug.

CollectionItem

A class for a CMS item in a Collection or ManagedCollection.

fieldData

The fields and corresponding values of the Collection item.

id

A unique identifier for a Collection item.

remove

()

Remove the item from the Collection.

setAttributes

()

Set the values of the fields of the CMS item.

slug

Slug value of the CMS item.

EnumCase

An Enum Case for an Enum Field.

id

A unique identifier for the Enum Case.

name

The name of the Enum Case.

remove

Remove the Enum Case.

setAttributes

Update the attributes of the Enum Case.

EnumField

An enum field.

addCase

()

Add an Enum Case.

EnumCase

An Enum Case for an Enum Field.

cases

The cases of the Enum Field.

setCaseOrder

()

Set the order of the Enum Field's Enum Cases.

ManagedCollection

A CMS Collection that is controlled by a Plugin.

addItems

()

Add new items or update existing ones if their IDs match.

getFields

()

Get all fields on the Collection.

getItemIds

()

Retrieve all Item IDs in a Managed Collection.

removeItems

()

Remove CMS items by their ID.

setAsActive

()

Open this Collection in the Editor.

setFields

()

Add, update, or remove Collection fields.

setItemOrder

()

Arrange CMS items in a specific order.

Localization (Beta) APIs

Framer provides APIs to interact with our Localization functionality. The key pieces of Localization in Framer are Locales, Localization Groups, and Localization Sources. Locales are a language paired with an optional region, like English or English (Canada). Localization groups are things like pages or CMS items that contain one or more Localization sources. Localization sources are the strings from your site, along with their localized values.

getActiveLocale

()

Get the currently active Locale.

getDefaultLocale

()

Get the default locale of the project.

getLocales

()

Get all Locales in the project.

getLocalizationGroups

()

Get all Localization Groups in the project.

setLocalizationData

()

Update localization data.

Locale

A Locale in your project.

code

The language code of the Locale.

fallbackLocaleId

The ID of the fallback Locale.

id

A unique identifier for a Locale.

name

The name of the Locale.

slug

Slug value of the Locale.

LocalizationGroup

A group of Localization Sources.

id

A unique identifier for a Localization Group.

name

The name of a Localization Group.

sources

The Localization Sources in the Localization Group.

statusByLocale

The status of the Localization Group in each Locale.

supportsExcludedStatus

Whether a Localization Group supports the "excluded" status.

type

The type of a Localization Group.

LocalizationSource

A localizable string on your site.

LocalizationSource

A localizable string on your site.

id

A unique identifier for a Localization Source.

name

The name of a Localization Source.

type

The type of value for this Localization Source.

value

The current value of the Localization Source in the default locale.

valueByLocale

Localized values and metadata for each Locale.

LocalizationValue

The localized value and assocaited metadata for a Locale.

LocalizationValue

The localized value and assocaited metadata for a Locale.

lastEdited

The time the Localized Value was last edited at.

readonly

Whether the value is read only and therefore cannot be updated.

status

The status of the Localization Value.

value

The actual text of the Localization Value

warning

A warning about the Localization Value.

Canvas APIs

Drag & Drop

Allow any HTML element to become draggable.

DragData

An object that represents the data to be dragged.

Draggable

A React component that makes it's child draggable.

onDragComplete

()

A callback triggered when a drag finishes.

makeDraggable

()

Allow any HTML element to become draggable.

Plugin UI

A set of functions for opening and closing the Plugin itself, along with options setting a specific size for your Plugin. Plugins are able to run completely UI-less if desired.

`showUI(options)`

`hideUI()`

`closePlugin(message?: string)`

framer.showUI({
  position: "center",
  height: 300,
  width: 220
})

Modes

A property with the current mode. Modes are used to understand the context in which the Plugin is being run, and adjust logic as needed. Learn more in the mode guide.

`mode`

User

Information about a the current user logged into Framer. Returns the name of the user, as well as a hashed User ID to uniquely identify the current user.

`getCurrentUser()`

Project

Information about the current Framer Project. Returns the display name of the Project as well as a hashed Project ID. This ID cannot be used to access the Project.

`getProjectInfo()`

Selection

Functions for reading, setting, or listening to the current selection on the Canvas. The returned list can range from zero items to a very large list of items.

`getSelection()`

`setSelection(nodeIds)`

`subscribeToSelection(callback)`

const [selection, setSelection] = useState<CanvasNode[]>([])

useEffect(() => {
    return framer.subscribeToSelection(setSelection)
}, [])

console.log(`Selected ${selection.length} item(s)`)

Assets

A selection of functions for working with Images, Files, and SVGs. The high-level add and set functions are designed to work in most cases and automatically handle uploading for you. Learn more in the working with Assets guide.

`addImage(imageAsset)`

`setImage(imageAsset)`

`uploadImage(file)`

`uploadFile(file)`

`uploadFiles(files[])`

`addSvg(svgString)`

Components

Functions for utilising Components in your Plugin. Learn more in the Component guide.

`addComponentInstance({ url, attributes })`

`addDetachedComponentLayers({ url, layout, attributes })`

Text

A selection of functions for working with text layers and their content.

`getText()`

`setText(text)`

`addText(text)`

`subscribeToText(callback)`

Custom Code

With Custom Code your plugin can install code snippets in a user's Website via <script> tags. Custom Code added by a Plugin appears in a separate section of a Project’s site settings specifically for Plugins. This can be used to load external scripts on a site. Custom code should be valid HTML.

`setCustomCode(options)`

`getCustomCode()`

`subscribeToCustomCode(callback)`

When setting Custom Code, you must provide the html string, as well as a location.

framer.setCustomCode({ 
  html: '<script src="https://example.com/script.js"></script>',
  location: "bodyEnd" 
})

The location property has the following values:

headStart - Injects the code snippet at the start of the HTML <head> tag
headEnd - Injects the code snippet at the end of the HTML <head> tag
bodyStart - Injects the code snippet at the start of the <body> tag
bodyEnd - injects the code snippet at the end of the <body> tag

Setting the html value back to null clears the installed code snippet.

framer.setCustomCode({ 
  html: null,
  location: "bodyEnd" 
})

Storing Data

Functions for storing data that your Plugin case use across users and sessions. Learn about the different ways to store data in our Data guide.

`getPluginData(key)`

`setPluginData(key, value)`

`getPluginDataKeys()`

Styles

A set of functions for creating, reading and manipulating the Color and Text Styles in a Project. Learn more in our Styles guide.

`createColorStyle(attributes)`

`getColorStyle(id)`

`getColorStyles()`

`subscribeToColorStyles(callback)`

`createTextStyle(attributes)`

`getTextStyle(id)`

`getTextStyles()`

`subscribeToTextStyles(callback)`

Fonts

Plugins can use typefaces available in the Font Picker to get information about specific fonts or to apply them to Text Styles.

`getFont(family)`

`getFonts()`

Unlike the Font Picker, which groups fonts by typeface, getFonts will list individual fonts for each weight and style. You can think these as separate font files.

await framer.getFonts()

[
  //..
  {
    family: "Inter",
    weight: 900,
    style: "normal"
  },
  {
    family: "Noto Sans",
    weight: 400,
    style: "normal"
  },
  //..
]

To get a specific font from a family, use getFont and pass in the family name. This is not case sensitive. By default, this will return a font in the family that has a normal weight and style.

// Get Noto Sans with a weight of 400 in a normal style.
const font = await framer.getFont("Noto Sans")

// Get Noto Sans with a weight of 800 in an italic style.
const font = await framer.getFont("Noto Sans", {
  weight: 800,
  style: "italic"
})

Make sure to check that a font exists before using it. If a font does not exist, getFont will return null.

Note: Custom Fonts are not available to Plugins

// Scroll and zoom the viewport to show a specific node.
await framer.zoomIntoView("node-id")

// Scroll and zoom to fit multiple nodes into the viewport.
await framer.zoomIntoView(["node-id-1", "node-id-2"])

Changelog

Concepts

Changelog

Concepts