Interface Context

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

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

Properties

`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

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

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

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

addListener

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

removeListener

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

openViewer

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

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

createPage

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

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

Interface Context

Index

Properties

Methods

Properties

Readonlyroot

Example

ReadonlycurrentFile

Returns

Example

ReadonlycurrentPage

Example

Readonlyviewport

Example

Readonlyhistory

Example

Readonlylibrary

Example

Readonlyfonts

Example

ReadonlycurrentUser

Example

ReadonlyactiveUsers

Example

Readonlytheme

Example

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 null | Group

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 null | Boolean

Example

createShapeFromSvg

Parameters

Returns null | Group

Example

createText

Parameters

Returns null | Text

Example

generateMarkup

Parameters

Optionaltype?: "html" | "svg"

`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