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);
        sendMessage: ((message: unknown) => void);
        onMessage: (<T>(callback: ((message: T) => void)) => void);
    };
    utils: ContextUtils;
    closePlugin: (() => void);
    on<T>(type: T, callback: ((event: EventsMap[T]) => void), props?: {
        [key: string]: unknown;
    }): symbol;
    off(listenerId: symbol): void;
    root: null | Shape;
    currentFile: null | File;
    currentPage: null | Page;
    viewport: Viewport;
    history: HistoryContext;
    library: LibraryContext;
    fonts: FontsContext;
    currentUser: User;
    activeUsers: ActiveUser[];
    theme: Theme;
    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[]): null | Group;
    ungroup(group: Group, ...other: Group[]): void;
    createRectangle(): Rectangle;
    createBoard(): Board;
    createEllipse(): Ellipse;
    createPath(): Path;
    createBoolean(boolType: BooleanType, shapes: Shape[]): null | Boolean;
    createShapeFromSvg(svgString: string): null | Group;
    createText(text: string): null | Text;
    generateMarkup(shapes: Shape[], options?: {
        type?: "html" | "svg";
    }): string;
    generateStyle(shapes: Shape[], options?: {
        type?: "css";
        withPrelude?: boolean;
        includeChildren?: boolean;
    }): string;
    openViewer(): void;
    createPage(): Page;
    openPage(page: Page): 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);
    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});
```
- - (name, url, options?): void
  - Parameters
    - name: string
      title of the plugin, it'll be displayed on the top of the modal
    - url: string
      of the plugin
    - Optionaloptions: {
      width: number;
      height: number;
      }
      height and width of the modal.
      
      width: number
      height: number
    Returns void
sendMessage: ((message: unknown) => void)
Sends a message to the plugin UI.
Example
```
this.sendMessage({ type: 'example-type', content: 'data we want to share' });
```
- - (message): void
  - Parameters
    - message: unknown
      content usually is an object
    Returns void
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 })});
```
- - <T>(callback): void
  - Type Parameters
    - T
    Parameters
    - callback: ((message: T) => void)
      A function that will be called whenever a message is received. The function receives a single argument, message, which is of type T.
      
      (message): void
      Parameters
      message: T
      Returns void
    Returns void

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: null | Shape

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

Example

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

`Readonly`currentFile

currentFile: null | File

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: null | Page

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

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>(type, callback, props?): symbol
Adds an event listener for the specified event type. Subscribing to events requires content:read permission.

The following are the posible 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 (currentlly: either dark or light)
- documentsaved: event emitted afther 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.
  - - (event): void
    - Parameters
      event: EventsMap[T]
      Returns void
- Optionalprops: {
  [key: string]: unknown;
  }
  The properties for the current event handler. Only makes sense for specific events.
  - [key: string]: unknown
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:89

off

off(listenerId): 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:106

shapesColors

shapesColors(shapes): (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 Omit.shapesColors
- Defined in index.d.ts:808

replaceColor

replaceColor(shapes, oldColor, newColor): 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 Omit.replaceColor
- Defined in index.d.ts:818

uploadMediaUrl

uploadMediaUrl(name, url): 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 Omit.uploadMediaUrl
- Defined in index.d.ts:838

uploadMediaData

uploadMediaData(name, data, mimeType): 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 Omit.uploadMediaData
- Defined in index.d.ts:852

group

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

ungroup

ungroup(group, ...other): void

Ungroups the specified group. Requires content:write permission.

Parameters

group: Group
The group to ungroup.
Rest...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]);
}

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 Omit.createBoard
- Defined in index.d.ts:954

createEllipse

createEllipse(): Ellipse

Use this method to create the shape of a 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 a 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 Omit.createPath
- Defined in index.d.ts:1017

createBoolean

createBoolean(boolType, shapes): null | Boolean
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 null | Boolean
Returns the newly created Boolean shape resulting from the boolean operation.
Example
```
const booleanShape = context.createBoolean('union', [shape1, shape2]);
```
Inherited from Omit.createBoolean
- Defined in index.d.ts:1029

createShapeFromSvg

createShapeFromSvg(svgString): null | Group
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 null | Group
Returns the newly created Group containing the shapes from the SVG.
Example
```
const svgGroup = context.createShapeFromSvg('<svg>...</svg>');
```
Inherited from Omit.createShapeFromSvg
- Defined in index.d.ts:1040

createText

createText(text): null | Text

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

Parameters

text: string
The text content for the Text shape.

Returns null | Text

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

generateStyle

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

openViewer

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

Returns void
Inherited from Omit.openViewer
- Defined in index.d.ts:1124

createPage

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

Returns Page
Inherited from Omit.createPage
- Defined in index.d.ts:1129

openPage

openPage(page): void
Changes the current open page to given page. Requires content:read permission.
Parameters
- page: Page
  the page to open
Returns void
Example
```
context.openPage(page);
```
Inherited from Omit.openPage
- Defined in index.d.ts:1140

alignHorizontal

alignHorizontal(shapes, direction): 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 Omit.alignHorizontal
- Defined in index.d.ts:1148

alignVertical

alignVertical(shapes, direction): 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 Omit.alignVertical
- Defined in index.d.ts:1159

distributeHorizontal

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

distributeVertical

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

flatten

flatten(shapes): 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 Omit.flatten
- Defined in index.d.ts:1178

Interface Penpot

Hierarchy

Index

Properties

Methods

Properties

ui

Type declaration

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

Example

Parameters

width: number

height: number

Returns void

sendMessage: ((message: unknown) => void)

Example

Parameters

Returns void

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

Example

Type Parameters

Parameters

Parameters

Returns void

Returns void

utils

closePlugin

Example

Readonlyroot

Example

ReadonlycurrentFile

Returns

Example

ReadonlycurrentPage

Example

Readonlyviewport

Example

Readonlyhistory

Example

Readonlylibrary

Example

Readonlyfonts

Example

ReadonlycurrentUser

Example

ReadonlyactiveUsers

Example

Readonlytheme

Example

selection

Example

Methods

on

Type Parameters

Parameters

Parameters

Returns void

[key: string]: unknown

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

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

`Readonly`root

`Readonly`currentFile

`Readonly`currentPage

`Readonly`viewport

`Readonly`history

`Readonly`library

`Readonly`fonts

`Readonly`currentUser

`Readonly`activeUsers

`Readonly`theme

`Optional`type?: "html" | "svg"

`Optional`type?: "css"

`Optional`withPrelude?: boolean

`Optional`includeChildren?: boolean