Interface Context

Represents the context of Penpot, providing access to various Penpot functionalities and data.

interface Context {
    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>;
    addListener<T extends keyof EventsMap>(
        type: T,
        callback: (event: EventsMap[T]) => void,
        props?: { [key: string]: unknown },
    ): symbol;
    removeListener(listenerId: symbol): void;
    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[];
}

Properties

`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

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

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

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]);
```
- 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>');
```
- 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>');
```
- 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);
```
- 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);
```
- 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);
```
- Defined in index.d.ts:1219

addListener

addListener<T extends keyof EventsMap>(
    type: T,
    callback: (event: EventsMap[T]) => void,
    props?: { [key: string]: unknown },
): symbol
Adds the current callback as an event listener
Type Parameters
- T extends keyof EventsMap
Parameters
- type: T
- callback: (event: EventsMap[T]) => void
- Optionalprops: { [key: string]: unknown }
Returns symbol
Example
```
const listenerId = context.addListener('selectionchange', (event) => {
  console.log(event);
});
```
- Defined in index.d.ts:1231

removeListener

removeListener(listenerId: symbol): void
Removes the listenerId from the list of listeners
Parameters
- listenerId: symbol
Returns void
Example
```
context.removeListener(listenerId);
```
- Defined in index.d.ts:1245

openViewer

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

Returns void
- Defined in index.d.ts:1250

createPage

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

Returns Page
- 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);
```
- 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
- 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
- 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
- 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
- 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[]
- Defined in index.d.ts:1305

Interface Context

Index

Properties

Methods

Properties

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

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

Returns Rectangle

Example

createBoard

Returns Board

Example

createEllipse

Returns Ellipse

Example

createPath

Returns Path

Example

createBoolean

Parameters

Returns Boolean | null

Example

createShapeFromSvg

Parameters

Returns Group | null

Example

createShapeFromSvgWithImages

Parameters

Returns Promise<Group | null>

Example

createText

`Readonly`root

`Readonly`currentFile

`Readonly`currentPage

`Readonly`viewport

`Readonly`flags

`Readonly`history

`Readonly`library

`Readonly`fonts

`Readonly`currentUser

`Readonly`activeUsers

`Readonly`theme

`Readonly`localStorage