API Reference

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

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.

`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.

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.

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

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

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

Drag & Drop

You can make images, SVG, and component instances, and detached component layers draggable using the framer.makeDraggable() API. The function requires an HTML element as its first argument, and a function to generate the drag data as its second argument.

`makeDraggable(element, getDragData)`

`<Draggable />`

The following data types can be inserted via dragging.

image
svg
componentInstance
detachedComponentLayers

An example of this for an Icon Plugin would be a button with a click event which is also wrapped with the Draggable component. This allows for either clicking or dragging.

<Draggable data={{
  type: "svg",
  svg: framerIcon,
  invertInDarkMode: true // Invert drag preview in dark mode
}}>
  <button onClick={() => framer.addSVG({ svg: framerIcon })}>
    {/* Icon asset */}
  </button>
</Draggable>

The process for doing this with a Component is quite similar, but with a different set of options for using a Component URL and allowing for layout block functionality.

<Draggable
    data={{
        type: "detachedComponentLayers",
        url: componentURL,
        layout: true, // Insert layers as a layout block
    }}
>
    <button
        onClick={() => {
            void framer.addDetachedComponentLayers({
                url: componentURL,
                layout: true,
            })
        }}
    >
      {/* Component asset */}
    </button>
</Draggable>

CMS

Getters for CMS Collections within a Project. Learn more about the CMS functionality with Plugins and the different types of Collections in our CMS Guide.

`getCollection(id)`

`getManagedCollection()`

`getActiveCollection()`

`getCollections()`

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

Previous

Next

Previous

Next