Search

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.

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.

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.

`subscribeToSelection(callback)`

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

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

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

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

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

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

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

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

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

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(imageAsset)`

`uploadImages(imageAsset[])`

`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" 
})

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

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" 
})

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

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"
  },
  //..
]

await framer.getFonts()

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

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"
})

// 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"
})

// 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

Nodes

Low-level API for working with Nodes. Useful for doing very specific tasks that may not be covered by the higher-level APIs. Learn more in our working with Nodes guide.

`createFrameNode(attributes)`

`cloneNode(nodeId)`

`removeNode(nodeId)`

`getCanvasRoot()`

`subscribeToCanvasRoot(callback)`

`getNode(nodeId)`

`getParent(nodeId)`

`getChildren(nodeId)`

`getRect(nodeId)`

`setAttributes(nodeId, attributes)`

`setParent(nodeId, parentId)`

`getNodesWithType(type)`

`getNodesWithAttribute(attribute)`

`getNodesWithAttributeSet(attribute)`

`node.navigateTo(opts)`

API Reference

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

Use the Navigation API to programmatically navigate the UI to a canvas node, a CMS collection item, or a code file. Plugins can optionally select targets, zoom to canvas layers, or focus a specific field in the item editor.

navigateTo

()

Navigate the Framer UI to a target by its ID

zoomIntoView

()

Pans and zooms the viewport to center a single or group of nodes

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.

setBackgroundMessage

()

Set a message to display while the plugin is hidden

closePlugin

()

Close and terminate the plugin.

hideUI

()

Hide the plugin window.

notify

()

Display a notification message

setCloseWarning

()

When enabled, a modal confirmation will appear before close to confirm the action.

setMenu

()

showContextMenu

()

Show a context menu at a given location.

showUI

()

Show the plugin window.

User APIs

getCurrentUser

()

Information about the user that's interacting with the plugin.

User

A Framer user.

apiVersion1Id

Deprecated, use id.

avatarUrl

Full URL of user's profile picture, if they have one.

id

User's ID, represented as a 64-lowercase-character hexadecimal string.

initials

2-uppercase-character acronym of user's name, for when there is no avatar.

name

User's full name.

Code File API

The CodeFile API allows plugins to create, read, update, and manage code files within a Framer project. A code file exports either overrides or code components.

createCodeFile

()

Create a new code file in the project.

getCodeFile

()

Get a specific code file by its ID.

getCodeFiles

()

Get all code files in the project.

subscribeToCodeFiles

()

Subscribe to changes in code files across the project.

subscribeToOpenCodeFile

()

Subscribe to changes in the Code Editor’s active file.

CodeFile

A class representing a code file in a Framer project.

content

The current content/source code of the file.

exports

Array of exports available in this code file.

getVersions

()

Get all versions/history of this code file.

id

The unique identifier of the code file.

lint

()

Run linting on the code file content.

name

The name of the code file (e.g., "MyComponent.tsx").

navigateTo

()

Get all versions/history of this code file.

path

The file system path of the code file.

remove

()

Remove the code file from the project.

rename

()

Rename the code file.

setFileContent

()

Set the content of the code file.

typecheck

()

Run TypeScript type checking on the code file.

CodeFileExport

Union type representing exports from a code file.

insertURL

URL for inserting the component

isDefaultExport

Whether this is a default export

name

Export name

type

Discriminator

CodeFileVersion

Represents a historical version of a code file.

createdAt

The creation timestamp.

createdBy

The user that created this version.

getContent

()

Retrieve content for this version.

id

The version identifier.

name

The file name at this version.

Canvas APIs

Framer provides APIs to interact with our Canvas. These APIs range from directly editing Nodes, to Images, and Drag & Drop. Learn more about Nodes in our guide.

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.

Traits

Allow to get or edit node.

overflow

Controls how content that exceeds an element's box is handled.

overflowX

Controls horizontal overflow behavior.

overflowY

Controls vertical overflow behavior.

aspectRatio

Width-to-height ratio

backgroundColor

Background color in RGBA format or as a ColorStyle instance

backgroundGradient

Background gradient

backgroundImage

Background image asset

border

Border properties

borderRadius

Border radius for rounded corners

bottom

Distance from bottom edge when using absolute/fixed positioning

centerX

Center anchor position as percentage

centerY

Center anchor position as percentage

collectionId

Collection ID for the web page

componentIdentifier

Identifier of the component

componentName

Name of the component

controls

Property control values for code components

font

Font selection for text

gap

Spacing between items in a layout

gesture

Gesture state for component variants

gridAlignment

How items are aligned within the grid

gridColumnCount

Number of columns in the grid

gridColumnMinWidth

Minimum width of grid columns in pixels

gridColumnWidth

Width of grid columns in pixels

gridColumnWidthType

Type of column width sizing

gridItemColumnSpan

Number of columns to span

gridItemFillCellHeight

Whether to fill the grid cell height

gridItemFillCellWidth

Whether to fill the grid cell width

gridItemHorizontalAlignment

Horizontal alignment within grid cell

gridItemRowSpan

Number of rows to span

gridItemVerticalAlignment

Vertical alignment within grid cell

gridRowCount

Number of rows in the grid

gridRowHeight

Height of grid rows in pixels

gridRowHeightType

Type of row height sizing

height

Height of the node

imageRendering

How images should be rendered when scaled

inheritsFromId

ID of the node this variant inherits from

inlineTextStyle

Apply a text style preset

isBreakpoint

Whether this is a breakpoint

isPrimaryBreakpoint

Whether this is the primary breakpoint

isPrimaryVariant

Whether this is the primary variant

isVariant

Whether this is a component variant

layout

Enables stack or grid layout

left

Distance from left edge when using absolute/fixed positioning

link

URL or internal page link

linkOpenInNewTab

Whether to open link in new tab

locked

Whether the node is locked for editing

maxHeight

Maximum height constraint

maxWidth

Maximum width constraint

minHeight

Minimum height constraint

minWidth

Minimum width constraint

name

The name of the node displayed in the layers panel

opacity

Opacity of the node

padding

Inner spacing of a container with layout

path

URL path for the web page

position

Positioning behavior of the node

right

Distance from right edge when using absolute/fixed positioning

rotation

Rotation angle in degrees

stackAlignment

How items are aligned perpendicular to the stack direction

stackDirection

Direction of items in a stack layout

stackDistribution

How items are distributed in a stack layout

stackWrapEnabled

Whether items should wrap to the next line

svg

SVG markup content

top

Distance from top edge when using absolute/fixed positioning

visible

Whether the node is visible on the canvas

width

Width of the node

textTruncation

Specifies the maximum number of lines a text node can display before being truncated with an ellipsis

zIndex

Sets the stacking order of positioned elements. Higher values appear on top of lower values.

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.

managedBy

Returns who manages the 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.

createCollection

()

Add a new CMS Collection.

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.

navigateTo

()

Navigate the UI to this 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.

nameByLocale

Localized values for the name of the Enum Case.

remove

Remove the Enum Case.

setAttributes

Update the attributes of the Enum Case.

EnumField

An enum field.

EnumCase

An Enum Case for an Enum Field.

addCase

()

Add an Enum Case.

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.

createManagedCollection

()

Add a new plugin-managed CMS Collection.

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 API

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.

Concepts