Interface Penpot

These are methods and properties available on the penpot global object.

interface Penpot {
    ui: {
        open: (
            name: string,
            url: string,
            options?: { width: number; height: number },
        ) => void;
        size: { width: number; height: number } | null;
        resize: (width: number, height: number) => void;
        sendMessage: (message: unknown) => void;
        onMessage: <T>(callback: (message: T) => void) => void;
    };
    utils: ContextUtils;
    closePlugin: () => void;
    on<T extends keyof EventsMap>(
        type: T,
        callback: (event: EventsMap[T]) => void,
        props?: { [key: string]: unknown },
    ): symbol;
    off(listenerId: symbol): void;
    root: Shape | null;
    currentFile: File | null;
    currentPage: Page | null;
    viewport: Viewport;
    flags: Flags;
    history: HistoryContext;
    library: LibraryContext;
    fonts: FontsContext;
    currentUser: User;
    activeUsers: ActiveUser[];
    theme: Theme;
    localStorage: LocalStorage;
    selection: Shape[];
    shapesColors(shapes: Shape[]): (Color & ColorShapeInfo)[];
    replaceColor(shapes: Shape[], oldColor: Color, newColor: Color): void;
    uploadMediaUrl(name: string, url: string): Promise<ImageData>;
    uploadMediaData(
        name: string,
        data: Uint8Array,
        mimeType: string,
    ): Promise<ImageData>;
    group(shapes: Shape[]): Group | null;
    ungroup(group: Group, ...other: Group[]): void;
    createRectangle(): Rectangle;
    createBoard(): Board;
    createEllipse(): Ellipse;
    createPath(): Path;
    createBoolean(boolType: BooleanType, shapes: Shape[]): Boolean | null;
    createShapeFromSvg(svgString: string): Group | null;
    createShapeFromSvgWithImages(svgString: string): Promise<Group | null>;
    createText(text: string): Text | null;
    generateMarkup(
        shapes: Shape[],
        options?: { type?: "html" | "svg" },
    ): string;
    generateStyle(
        shapes: Shape[],
        options?: {
            type?: "css";
            withPrelude?: boolean;
            includeChildren?: boolean;
        },
    ): string;
    generateFontFaces(shapes: Shape[]): Promise<string>;
    openViewer(): void;
    createPage(): Page;
    openPage(page: string | Page, newWindow?: boolean): void;
    alignHorizontal(
        shapes: Shape[],
        direction: "center" | "left" | "right",
    ): void;
    alignVertical(
        shapes: Shape[],
        direction: "center" | "top" | "bottom",
    ): void;
    distributeHorizontal(shapes: Shape[]): void;
    distributeVertical(shapes: Shape[]): void;
    flatten(shapes: Shape[]): Path[];
}

Hierarchy

Omit<Context, "addListener" | "removeListener">
- Penpot

Properties

ui

ui: {
    open: (
        name: string,
        url: string,
        options?: { width: number; height: number },
    ) => void;
    size: { width: number; height: number } | null;
    resize: (width: number, height: number) => void;
    sendMessage: (message: unknown) => void;
    onMessage: <T>(callback: (message: T) => void) => void;
}

Type Declaration

open: (name: string, url: string, options?: { width: number; height: number }) => void
Opens the plugin UI. It is possible to develop a plugin without interface (see Palette color example) but if you need, the way to open this UI is using penpot.ui.open. There is a minimum and maximum size for this modal and a default size but it's possible to customize it anyway with the options parameter.
Example
```
penpot.ui.open('Plugin name', 'url', {width: 150, height: 300});
```
size: { width: number; height: number } | null
resize: (width: number, height: number) => void
Resizes the plugin UI.
Example
```
penpot.ui.resize(300, 400);
```

sendMessage: (message: unknown) => void

Sends a message to the plugin UI.

Example

this.sendMessage({ type: 'example-type', content: 'data we want to share' });

onMessage: <T>(callback: (message: T) => void) => void
This is usually used in the plugin.ts file in order to handle the data sent by our plugin
Example
```
penpot.ui.onMessage((message) => {if(message.type === 'example-type' { ...do something })});
```

utils

utils: ContextUtils

Provides access to utility functions and context-specific operations.

closePlugin

closePlugin: () => void

Closes the plugin. When this method is called the UI will be closed.

Example

penpot.closePlugin();

`Readonly`root

root: Shape | null

The root shape in the current Penpot context. Requires content:read permission.

Example

const rootShape = context.root;
console.log(rootShape);

`Readonly`currentFile

currentFile: File | null

Retrieves file data from the current Penpot context. Requires content:read permission.

Returns

Returns the file data or null if no file is available.

Example

const fileData = context.currentFile;
console.log(fileData);

`Readonly`currentPage

currentPage: Page | null

The current page in the Penpot context. Requires content:read permission.

Example

const currentPage = context.currentPage;
console.log(currentPage);

`Readonly`viewport

viewport: Viewport

The viewport settings in the Penpot context.

Example

const viewportSettings = context.viewport;
console.log(viewportSettings);

`Readonly`flags

flags: Flags

Provides flags to customize the API behavior.

`Readonly`history

history: HistoryContext

Context encapsulating the history operations

Example

const historyContext = context.history;
console.log(historyContext);

`Readonly`library

library: LibraryContext

The library context in the Penpot context, including both local and connected libraries. Requires library:read permission.

Example

const libraryContext = context.library;
console.log(libraryContext);

`Readonly`fonts

fonts: FontsContext

The fonts context in the Penpot context, providing methods to manage fonts. Requires content:read permission.

Example

const fontsContext = context.fonts;
console.log(fontsContext);

`Readonly`currentUser

currentUser: User

The current user in the Penpot context. Requires user:read permission.

Example

const currentUser = context.currentUser;
console.log(currentUser);

`Readonly`activeUsers

activeUsers: ActiveUser[]

An array of active users in the Penpot context. Requires user:read permission.

Example

const activeUsers = context.activeUsers;
console.log(activeUsers);

`Readonly`theme

theme: Theme

The current theme (light or dark) in Penpot.

Example

const currentTheme = context.theme;
console.log(currentTheme);

`Readonly`localStorage

localStorage: LocalStorage

Access to the localStorage proxy

selection

selection: Shape[]

The currently selected shapes in Penpot. Requires content:read permission.

Example

const selectedShapes = context.selection;
console.log(selectedShapes);

Methods

on

on<T extends keyof EventsMap>(
    type: T,
    callback: (event: EventsMap[T]) => void,
    props?: { [key: string]: unknown },
): symbol
Adds an event listener for the specified event type. Subscribing to events requires content:read permission.

The following are the possible event types:
- pagechange: event emitted when the current page changes. The callback will receive the new page.
- shapechange: event emitted when the shape changes. This event requires to send inside the props object the shape that will be observed. For example:
```
// Observe the current selected shape
penpot.on('shapechange', (shape) => console.log(shape.name), { shapeId: penpot.selection[0].id });
```
- selectionchange: event emitted when the current selection changes. The callback will receive the list of ids for the new selection
- themechange: event emitted when the user changes its theme. The callback will receive the new theme (currently: either dark or light)
- documentsaved: event emitted after the document is saved in the backend.
Type Parameters
- T extends keyof EventsMap
Parameters
- type: T
  The event type to listen for.
- callback: (event: EventsMap[T]) => void
  The callback function to execute when the event is triggered.
- Optionalprops: { [key: string]: unknown }
  The properties for the current event handler. Only makes sense for specific events.
Returns symbol
the listener id that can be used to call off and cancel the listener
Example
```
penpot.on('pagechange', () => {...do something}).
```
- Defined in index.d.ts:116

off

off(listenerId: symbol): void
Removes an event listener for the specified event type.
Parameters
- listenerId: symbol
  the id returned by the on method when the callback was set
Returns void
Example
```
const listenerId = penpot.on('contentsave', () => console.log("Changed"));
penpot.off(listenerId);
```
- Defined in index.d.ts:133

shapesColors

shapesColors(shapes: Shape[]): (Color & ColorShapeInfo)[]
Retrieves colors applied to the given shapes in Penpot. Requires content:read permission.
Parameters
- shapes: Shape[]
Returns (Color & ColorShapeInfo)[]
Returns an array of colors and their shape information.
Example
```
const colors = context.shapesColors(shapes);
console.log(colors);
```
Inherited from Context.shapesColors
- Defined in index.d.ts:907

replaceColor

replaceColor(shapes: Shape[], oldColor: Color, newColor: Color): void
Replaces a specified old color with a new color in the given shapes. Requires content:write permission.
Parameters
- shapes: Shape[]
- oldColor: Color
- newColor: Color
Returns void
Example
```
context.replaceColor(shapes, oldColor, newColor);
```
Inherited from Context.replaceColor
- Defined in index.d.ts:917

uploadMediaUrl

uploadMediaUrl(name: string, url: string): Promise<ImageData>
Uploads media to Penpot and retrieves its image data. Requires content:write permission.
Parameters
- name: string
  The name of the media.
- url: string
  The URL of the media to be uploaded.
Returns Promise<ImageData>
Returns a promise that resolves to the image data of the uploaded media.
Example
```
const imageData = await context.uploadMediaUrl('example', 'https://example.com/image.jpg');
console.log(imageData);

// to insert the image in a shape we can do
const board = penpot.createBoard();
const shape = penpot.createRectangle();
board.appendChild(shape);
shape.fills = [{ fillOpacity: 1, fillImage: imageData }];
```
Inherited from Context.uploadMediaUrl
- Defined in index.d.ts:937

uploadMediaData

uploadMediaData(
    name: string,
    data: Uint8Array,
    mimeType: string,
): Promise<ImageData>
Uploads media to penpot and retrieves the image data. Requires content:write permission.
Parameters
- name: string
  The name of the media.
- data: Uint8Array
  The image content data
- mimeType: string
Returns Promise<ImageData>
Returns a promise that resolves to the image data of the uploaded media.
Example
```
const imageData = await context.uploadMediaData('example', imageData, 'image/jpeg');
console.log(imageData);
```
Inherited from Context.uploadMediaData
- Defined in index.d.ts:951

group

group(shapes: Shape[]): Group | null
Groups the specified shapes. Requires content:write permission.
Parameters
- shapes: Shape[]
  An array of shapes to group.
Returns Group | null
Returns the newly created group or null if the group could not be created.
Example
```
const penpotShapesArray = penpot.selection;
penpot.group(penpotShapesArray);
```
Inherited from Context.group
- Defined in index.d.ts:967

ungroup

ungroup(group: Group, ...other: Group[]): void
Ungroups the specified group. Requires content:write permission.
Parameters
- group: Group
  The group to ungroup.
- ...other: Group[]
  Additional groups to ungroup.
Returns void
Example
```
const penpotShapesArray = penpot.selection;
// We need to make sure that something is selected, and if the selected shape is a group,
if (selected.length && penpot.utils.types.isGroup(penpotShapesArray[0])) {
  penpot.group(penpotShapesArray[0]);
}
```
Inherited from Context.ungroup
- Defined in index.d.ts:982

createRectangle

createRectangle(): Rectangle

Use this method to create the shape of a rectangle. Requires content:write permission.

Returns Rectangle

Example

const shape = penpot.createRectangle();
// just change the values like this
shape.name = "Example rectangle";

// for solid color
shape.fills = [{ fillColor: "#7EFFF5" }];
// for linear gradient color
shape.fills = [{
 fillColorGradient: {
   "type": "linear",
   "startX": 0.5,
   "startY": 0,
   "endX": 0.5,
   "endY": 1,
   "width": 1,
   "stops": [
     {
       "color": "#003ae9",
       "opacity": 1,
       "offset": 0
     },
     {
       "color": "#003ae9",
       "opacity": 0,
       "offset": 1
     }
   ]
 }
}];
// for a image fill
const imageData = await context.uploadMediaUrl('example', 'https://example.com/image.jpg');
shape.fills = [{ fillOpacity: 1, fillImage: imageData }];

shape.borderRadius = 8;
shape.strokes = [
 {
   strokeColor: "#2e3434",
   strokeStyle: "solid",
   strokeWidth: 2,
   strokeAlignment: "center",
 },
];

createBoard

createBoard(): Board
Use this method to create a board. This is the first step before anything else, the container. Requires content:write permission. Then you can add a gridlayout, flexlayout or add a shape inside the board. Just a heads-up: board is a board in Penpot UI.

Returns Board
Example
```
const board = penpot.createBoard();

// to add grid layout
board.addGridLayout();
// to add flex layout
board.addFlexLayout();

// to create a shape inside the board
const shape = penpot.createRectangle();
board.appendChild(shape);
```
Inherited from Context.createBoard
- Defined in index.d.ts:1053

createEllipse

createEllipse(): Ellipse

Use this method to create the shape of an ellipse. Requires content:write permission.

Returns Ellipse

Example

const shape = penpot.createEllipse();
// just change the values like this
shape.name = "Example ellipse";

// for solid color
shape.fills = [{ fillColor: "#7EFFF5" }];
// for linear gradient color
shape.fills = [{
 fillColorGradient: {
   "type": "linear",
   "startX": 0.5,
   "startY": 0,
   "endX": 0.5,
   "endY": 1,
   "width": 1,
   "stops": [
     {
       "color": "#003ae9",
       "opacity": 1,
       "offset": 0
     },
     {
       "color": "#003ae9",
       "opacity": 0,
       "offset": 1
     }
   ]
 }
}];
// for an image fill
const imageData = await context.uploadMediaUrl('example', 'https://example.com/image.jpg');
shape.fills = [{ fillOpacity: 1, fillImage: imageData }];

shape.strokes = [
 {
   strokeColor: "#2e3434",
   strokeStyle: "solid",
   strokeWidth: 2,
   strokeAlignment: "center",
 },
];

createPath

createPath(): Path
Use this method to create a path. Requires content:write permission.

Returns Path
Example
```
const path = penpot.createPath();
path.name = "My path";

// for solid color
path.fills = [{ fillColor: "#7EFFF5" }];
```
Inherited from Context.createPath
- Defined in index.d.ts:1116

createBoolean

createBoolean(boolType: BooleanType, shapes: Shape[]): Boolean | null
Creates a Boolean shape based on the specified boolean operation and shapes. Requires content:write permission.
Parameters
- boolType: BooleanType
  The type of boolean operation ('union', 'difference', 'exclude', 'intersection').
- shapes: Shape[]
  An array of shapes to perform the boolean operation on.
Returns Boolean | null
Returns the newly created Boolean shape resulting from the boolean operation.
Example
```
const booleanShape = context.createBoolean('union', [shape1, shape2]);
```
Inherited from Context.createBoolean
- Defined in index.d.ts:1128

createShapeFromSvg

createShapeFromSvg(svgString: string): Group | null
Creates a Group from an SVG string. Requires content:write permission.
Parameters
- svgString: string
  The SVG string representing the shapes to be converted into a group.
Returns Group | null
Returns the newly created Group containing the shapes from the SVG.
Example
```
const svgGroup = context.createShapeFromSvg('<svg>...</svg>');
```
Inherited from Context.createShapeFromSvg
- Defined in index.d.ts:1139

createShapeFromSvgWithImages

createShapeFromSvgWithImages(svgString: string): Promise<Group | null>
Creates a Group from an SVG string. The SVG can have images and the method returns a Promise because the shape will be available after all images are uploaded. Requires content:write permission.
Parameters
- svgString: string
  The SVG string representing the shapes to be converted into a group.
Returns Promise<Group | null>
Returns a promise with the newly created Group containing the shapes from the SVG.
Example
```
const svgGroup = await context.createShapeFromSvgWithImages('<svg>...</svg>');
```
Inherited from Context.createShapeFromSvgWithImages
- Defined in index.d.ts:1152

createText

createText(text: string): Text | null

Creates a Text shape with the specified text content. Requires content:write permission.

Parameters

text: string
The text content for the Text shape.

Returns Text | null

Returns the new created shape, if the shape wasn't created can return null.

Example

const board = penpot.createBoard();
let text;
text = penpot.createText();
// just change the values like this
text.growType = 'auto-height';
text.fontFamily = 'Work Sans';
text.fontSize = '12';
text.fills = [{fillColor: '#9f05ff', fillOpacity: 1}];
text.strokes = [{strokeOpacity: 1, strokeStyle: 'solid', strokeWidth: 2, strokeColor: '#deabff', strokeAlignment: 'outer'}];
board.appendChild(text);

generateMarkup

generateMarkup(shapes: Shape[], options?: { type?: "html" | "svg" }): string
Generates markup for the given shapes. Requires content:read permission
Parameters
- shapes: Shape[]
- Optionaloptions: { type?: "html" | "svg" }
Returns string
Example
```
const markup = context.generateMarkup(shapes, { type: 'html' });
console.log(markup);
```
Inherited from Context.generateMarkup
- Defined in index.d.ts:1186

generateStyle

generateStyle(
    shapes: Shape[],
    options?: {
        type?: "css";
        withPrelude?: boolean;
        includeChildren?: boolean;
    },
): string
Generates styles for the given shapes. Requires content:read permission
Parameters
- shapes: Shape[]
- Optionaloptions: { type?: "css"; withPrelude?: boolean; includeChildren?: boolean }
Returns string
Example
```
const styles = context.generateStyle(shapes, { type: 'css' });
console.log(styles);
```
Inherited from Context.generateStyle
- Defined in index.d.ts:1199

generateFontFaces

generateFontFaces(shapes: Shape[]): Promise<string>
Generates the fontfaces styles necessaries to render the shapes. Requires content:read permission
Parameters
- shapes: Shape[]
Returns Promise<string>
Example
```
const fontfaces = context.generateFontFaces(penpot.selection);
console.log(fontfaces);
```
Inherited from Context.generateFontFaces
- Defined in index.d.ts:1219

openViewer

openViewer(): void
Opens the viewer section. Requires content:read permission.

Returns void
Inherited from Context.openViewer
- Defined in index.d.ts:1250

createPage

createPage(): Page
Creates a new page. Requires content:write permission.

Returns Page
Inherited from Context.createPage
- Defined in index.d.ts:1255

openPage

openPage(page: string | Page, newWindow?: boolean): void
Changes the current open page to given page. Requires content:read permission.
Parameters
- page: string | Page
  the page to open (a Page object or a page UUID string)
- OptionalnewWindow: boolean
  if true opens the page in a new window, defaults to false
Returns void
Example
```
context.openPage(page);
```
Inherited from Context.openPage
- Defined in index.d.ts:1267

alignHorizontal

alignHorizontal(shapes: Shape[], direction: "center" | "left" | "right"): void
Aligning will move all the selected layers to a position relative to one of them in the horizontal direction.
Parameters
- shapes: Shape[]
  to align
- direction: "center" | "left" | "right"
  where the shapes will be aligned
Returns void
Inherited from Context.alignHorizontal
- Defined in index.d.ts:1275

alignVertical

alignVertical(shapes: Shape[], direction: "center" | "top" | "bottom"): void
Aligning will move all the selected layers to a position relative to one of them in the vertical direction.
Parameters
- shapes: Shape[]
  to align
- direction: "center" | "top" | "bottom"
  where the shapes will be aligned
Returns void
Inherited from Context.alignVertical
- Defined in index.d.ts:1286

distributeHorizontal

distributeHorizontal(shapes: Shape[]): void
Distributing objects to position them horizontally with equal distances between them.
Parameters
- shapes: Shape[]
  to distribute
Returns void
Inherited from Context.distributeHorizontal
- Defined in index.d.ts:1292

distributeVertical

distributeVertical(shapes: Shape[]): void
Distributing objects to position them vertically with equal distances between them.
Parameters
- shapes: Shape[]
  to distribute
Returns void
Inherited from Context.distributeVertical
- Defined in index.d.ts:1298

flatten

flatten(shapes: Shape[]): Path[]
Converts the shapes into Paths. If the shapes are complex will put together all its paths into one.
Parameters
- shapes: Shape[]
  to flatten
Returns Path[]
Inherited from Context.flatten
- Defined in index.d.ts:1305

Interface Penpot

Hierarchy

Index

Properties

Methods

Properties

ui

Type Declaration

open: (name: string, url: string, options?: { width: number; height: number }) => void

Example

size: { width: number; height: number } | null

resize: (width: number, height: number) => void

Example

sendMessage: (message: unknown) => void

Example

onMessage: <T>(callback: (message: T) => void) => void

Example

utils

closePlugin

Example

Readonlyroot

Example

ReadonlycurrentFile

Returns

Example

ReadonlycurrentPage

Example

Readonlyviewport

Example

Readonlyflags

Readonlyhistory

Example

Readonlylibrary

Example

Readonlyfonts

Example

ReadonlycurrentUser

Example

ReadonlyactiveUsers

Example

Readonlytheme

Example

ReadonlylocalStorage

selection

Example

Methods

on

Type Parameters

Parameters

Returns symbol

Example

off

Parameters

Returns void

Example

shapesColors

Parameters

Returns (Color & ColorShapeInfo)[]

Example

replaceColor

Parameters

Returns void

Example

uploadMediaUrl

Parameters

Returns Promise<ImageData>

Example

uploadMediaData

Parameters

Returns Promise<ImageData>

Example

group

Parameters

Returns Group | null

Example

ungroup

Parameters

Returns void

Example

createRectangle

`Readonly`root

`Readonly`currentFile

`Readonly`currentPage

`Readonly`viewport

`Readonly`flags

`Readonly`history

`Readonly`library

`Readonly`fonts

`Readonly`currentUser

`Readonly`activeUsers

`Readonly`theme

`Readonly`localStorage