# Overview

During your development, it's important to be able to debug your code and troubleshoot any issues that may arise. Fortunately, most modern browsers come with built-in developer tools that can help you do just that.

## Introduction

Check out this short video below on how to test and debug your add-on to help you get started more quickly, then read on for more details.<br/><br/>

<div style="display: flex; justify-content: center;">
    <iframe width="560" height="315" src="https://www.youtube.com/embed/XefQbfVOqto?si=VSxAEXYo-X2_pXMi" title="Testing and Debugging" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>

## Browser Developer Tools

Some of the key debugging features available in the browser developer tools include:

- **Console** - The console allows you to log messages and errors from your code, as well as execute JavaScript code and interact with the page or add-on.
- **Debugger** - The debugger allows you to set breakpoints in your code and step through it line by line, so you can see exactly what's happening at each stage of execution.
- **Network Monitor** - The network monitor allows you to monitor the network requests made by your add-on, so you can see how it's interacting with other resources and services.
- **Profiler** - The profiler allows you to analyze the performance of your add-on and identify areas where it may be slow or inefficient.

### Debugging Steps

To get started with debugging your add-on:

Access the developer tools by right-clicking on the browser window where Adobe Express is running, and selecting **Inspect Element** or **Inspect** from the context menu.

![inspect](./img/inspect.png)

<InlineAlert slots="text" variant="info"/>

Make sure you right click outside of the document area or you will not see the context menu pop-up. A good place to right-click is in the header of your add-on, where the title is. But if you're debugging because your add-on isn't running due to an issue, then you can right-click in the top frame of Adobe Express.

Next, navigate to the **Sources** tab, and from there you can locate and select the JavaScript file that contains the code you want to debug. You can locate it in the filesystem list or by using the **Search** tab. If the Search tab isn't displayed, clicking the 3 vertical dots will reveal it as shown below:

 ![locate source](./img/find-source.png)

Once you've selected your file, you can set breakpoints by clicking on the line number where you want the breakpoint to be set. This will pause the execution of your code at that breakpoint, allowing you to inspect variables and step through your code one line at a time.

By leveraging these tools, you will develop a deeper understanding of how your add-on is working, be able to identify and fix bugs more quickly, and benefit from a high-performing add-on.

<!-- <iframe aria-label="Browser Debugging Demo" src="https://drive.google.com/file/d/13FHUuRpVti9AH4nUwAMcvNcP6OzGpOc1/preview" width="640" height="480"></iframe> -->

### Console

When logging messages in your code, use the appropriate severity level that best describes the message. For example, an **Info** message might be used to provide general information about the application's state, while a **Warning** message might be used to alert developers about potential issues that could cause problems with the add-on. Similarly, an **Error** message might be used to indicate that an unexpected error has occurred, and a **Verbose** message might be used to see more descriptive information about the internal workings of the processing occurring in your add-on.

 Use the `console.*` methods as shown below to represent the severity level you would like to see for debugging:

```bash
    console.log('Info level)
    console.warn('Warning level')
    console.error('Error level)
    console.debug(Verbose level)
```

You can specifically filter which levels you want to view in the developer tools with the **Custom levels** drop-down as well to help you find your specific messages more quickly:

![custom levels](./img/log-levels.png)

To make it easier to filter and identify relevant messages in the console, it's also a good practice to include an obvious identifier as a prefix. This identifier could be a unique string or tag that is specific to your add-on, making it easier to distinguish your messages from other messages in the console. For example: `console.log([MyAddOn] - Initialization complete);`. Then you can filter on `MyAddOn` in the devtools and easily see what is relevant to your add-on.

Using appropriate severity levels and including identifiers in your console messages can greatly help improve the efficiency and effectiveness of your debugging, making it easier to identify and resolve issues.

### Printing JSON Data

Another helpful console method is `.dir()`, which displays a JSON representation of an object. For example, running `console.dir(document.head)` would generate the following output:

![console.dir method](./img/dir-method.png)

## Add-on SDK Developer Tools

The **Add-on Development** tools panel provides useful logging details and action buttons to allow for refreshing and clearing the data associated with your add-on, which are also useful for debugging and troubleshooting your add-on.

![add-ons tools screenshot](./img/add-on-devtools.png)

### Status messages

The **Add-on Development** panel also provides useful information via status messages like below to indicate when and where an error is occurring to help you target specific issues in your add-on. For instance, if an invalid value is found in the manifest, you will see something like the following:

![manifest error screenshot](./img/manifest-error.png)

### Refreshing and clearing data

The **Refresh** and **Clear data** buttons in the add-on developer tools can also be helpful when you want to manually force refresh your code (or when you update the manifest), or clear data you no longer want to persist. For instance, in the case of the ToDo list sample add-on (aka: `use-client-storage`), if you had added some items previously they will still be displayed when you open it again unless you actually clear the data. See the demo workflow video at the bottom of the boilerplate section for an example of this in action.

![add-ons tools clear data screenshot](./img/clear-data.png)

<InlineAlert slots="text" variant="success"/>

To make use of the add-on SDK's [ClientStorage API](../../references/addonsdk/instance-clientStorage.md) and store data in an underlying IndexedDB store, explore the ToDo list sample. You can view this store in the browser developer tools by navigating to the **Application** tab. Look for the IndexedDB store associated with your add-on ID to locate it. Here's an example:

![application tab indexed db screenshot](./img/application-indexed-db.png)

<InlineAlert slots="text" variant="info"/>

See [the Client Storage API](../../references/addonsdk/instance-clientStorage.md) for more details about storing and persisting data with your add-ons.
# Overview

This section provides a set of guides to help you in the debugging stage of your add-on.

## Introduction

During your development, it's important to be able to debug your code and troubleshoot any issues that may arise. Fortunately, most modern browsers come with built-in developer tools that can help you do just that.

Check out this short video below on how to test and debug your add-on to help you get started more quickly, then read through the rest of the guides provided in this section for more details.<br/><br/>

<div style="display: flex; justify-content: center;">
    <iframe width="560" height="315" src="https://www.youtube.com/embed/XefQbfVOqto?si=VSxAEXYo-X2_pXMi" title="Testing and Debugging" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>
# Known Issues & Limitations

## Supported Browsers

## Sandboxed iFrame Caveats
# Debugging with Visual Studio Code

If you are a Visual Studio Code user, you can easily debug your add-on by following the steps in this guide.

<!-- An example of this workflow is shown in the video below for reference:

<iframe aria-label="Debugging VS Code Demo" src="https://drive.google.com/file/d/1at1jXCTIi9TZWxwFn11su0PeEQZhUGFC/preview" width="640" height="480"></iframe> -->

## Steps

1. Begin by locating the existing `launch.json` file in the `.vscode` folder in the root of your project. This file will exist if you have created your add-on with the add-on CLI. Double check to ensure the URL points to `https://new.express.adobe.com/new/`.

   **NOTE:** If it's a sample add-on that you downloaded, you may need to create one first with the **create a launch.json file**.

   ![New launch.json file option](img/new-launch-json.png)

 Then copy in the JSON configuration included below (or copy one in from an add-on you previously generated).

  ```json
  {        
    "version": "0.1.0",
    "configurations": [
        {
            "type": "chrome",
            "request": "launch",
            "name": "Debug(Chrome) Add-On",
            "webRoot": "${workspaceFolder}",

            /**
            * For add-ons which donot specify the mappings automatically,
            * user will be required to secify the mappings under pathMapping property.
            */

            "pathMapping": {
                "index.html": "${workspaceFolder}/src/index.html"
            },

            /**
            * This will be the link of the document where the add-on is hosted
            * or the url of the new document where you want to load the add-on
            */
            "url": "https://new.express.adobe.com/new/"
        },
        {
            "type": "msedge",
            "request": "launch",
            "name": "Debug(MS Edge) Add-On",
            "webRoot": "${workspaceFolder}",

            /**
            * For add-ons which donot specify the mappings automatically,
            * user will be required to secify the mappings under pathMapping property.
            */

            "pathMapping": {
                "index.html": "${workspaceFolder}/src/index.html"
            },

            /**
            * This will be the link of the document where the add-on is hosted
            * or the url of the new document where you want to load the add-on
            */
            "url": "https://new.express.adobe.com/new/"
        }
    ]
  }
  ```

2. Start your add-on from your terminal as normal with `npm run start`.

3. Back in VS Code, click the **Run and Debug** option from the left panel and then select the profile related to where you want to debug (note that Chrome is the first one and selected by default but you can modify your configuration in the `launch.json` to your liking).

    ![launch.json file](img/vscode-debug-option.png)

    ![launch profiles](img/launch-profiles.png)

4. Once you have your selection set from above, simply hit the green play button outlined below to start debugging.

    ![start debugging](img/start-debug.png)

5. A new browser window will open for your debugging session directly to the Express URL you configured above. Connect to your add-on as you normally would in Express.

6. You can now set breakpoints as desired, and you will see the code execution stop with the line highlighted. You can also check the **DEBUG CONSOLE** window to see any console output directly in VS Code.

  ![debugging screenshot](img/debugging.png)

7. Note the toolbar added to the top of your screen in VS Code when you're in debug mode which allows you to step through your code after it's been stopped on a breakpoint.

  ![debugging tools](img/debugger-tool.png)
# Overview

This set of best practices are important to keep in mind as you develop your add-on since they can ultimately make or break the user experience with your add-on.

## Best Practices

- Design responsively and remember the width and height of your add-on panel will vary by device.

- If the user needs to drill down into multiple panels, ensure you provide a way for them to navigate back.

- If the user will be logging in to a 3rd party service, ensure you provide a way for them to log out through your add-on UI.

- It's best to use a vertical layout for your UI components, with full-width buttons and components and vertical scrolling for overflow.

- If your add-on contains a gallery of images, a grid layout can work well.

- Use the header to help provide context in cases where your add-on requires a multi-step workflow, and to help with navigation.

- Use a footer if your add-on requires vertical scrolling for a primary CTA to be shown if needed.

- If you're using a search, use placeholder text to guide users in what they can search for, and display the search results directly below the search field.

- Use loading and progress indicators to provide visual feedback while things are in process.

- Ensure your add-on is able to adapt seamlessly to appearance changes like if the theme changes from light to dark. Only the light theme will be supported at GA but you should still code your add-ons to adapt for when new support is added. **Note:** See the **SWC** sample for a reference on handling theme changes.

- Always build with accessibility in mind. For instance, consider tab order and color, dark mode etc. Adobe Spectrum CSS provides design guidelines for ensuring accessibility in [the design system base docs](https://spectrum.adobe.com/), but it's also automatically built in to the Spectrum Web Components and React Spectrum implementations.

- Light mode is currently the only theme available, but dark mode will be supported in the future, so be sure to consider how your UI will look in dark mode as well.
# Using Fonts in Add-ons

## Adobe Fonts

The following Adobe Express fonts are injected into the add-on and can be used automatically.

```css
{
    family: "adobe-clean",
    source: "url('https://use.typekit.net/af/c0160f/00000000000000007735dac8/30/l?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n4&v=3') format('woff2'), url('https://use.typekit.net/af/c0160f/00000000000000007735dac8/30/d?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n4&v=3') format('woff'), url('https://use.typekit.net/af/c0160f/00000000000000007735dac8/30/a?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n4&v=3') format('opentype')",
    weight: "400",
    style: "normal",
    display: "auto"
},
{
    family: "adobe-clean",
    source: "url('https://use.typekit.net/af/95bf80/00000000000000007735dacd/30/l?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=i4&v=3') format('woff2'), url('https://use.typekit.net/af/95bf80/00000000000000007735dacd/30/d?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=i4&v=3') format('woff'), url('https://use.typekit.net/af/95bf80/00000000000000007735dacd/30/a?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=i4&v=3') format('opentype')",
    weight: "400",
    style: "italic",
    display: "auto"
},
{
    family: "adobe-clean",
    source: "url('https://use.typekit.net/af/5c07ba/00000000000000007735dad8/30/l?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n7&v=3') format('woff2'), url('https://use.typekit.net/af/5c07ba/00000000000000007735dad8/30/d?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n7&v=3') format('woff'), url('https://use.typekit.net/af/5c07ba/00000000000000007735dad8/30/a?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n7&v=3') format('opentype')",
    weight: "700",
    style: "normal",
    display: "auto"
},
{
    family: "adobe-clean",
    source: "url('https://use.typekit.net/af/2dda0a/00000000000000007735dad4/30/l?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n8&v=3') format('woff2'), url('https://use.typekit.net/af/2dda0a/00000000000000007735dad4/30/d?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n8&v=3') format('woff'), url('https://use.typekit.net/af/2dda0a/00000000000000007735dad4/30/a?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n8&v=3') format('opentype')",
    weight: "800",
    style: "normal",
    display: "auto"
},
{
    family: "adobe-clean",
    source: "url('https://use.typekit.net/af/bc79c1/00000000000000007735dad9/30/l?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n9&v=3') format('woff2'), url('https://use.typekit.net/af/bc79c1/00000000000000007735dad9/30/d?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n9&v=3') format('woff'), url('https://use.typekit.net/af/bc79c1/00000000000000007735dad9/30/a?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n9&v=3') format('opentype')",
    weight: "900",
    style: "normal",
    display: "auto"
}
```

<InlineAlert slots="text" variant="info"/>

In the near future, all of the Adobe Express fonts will be injected for use, however, at the moment these specific fonts are being injected for you to access in your add-on without having to bundle them.

## Importing Fonts from a URL

You can use a font with a URL by either linking to it via an import rule, via the &lt;link&gt; tag, or `font-face`.

<InlineAlert slots="text" variant="success"/>

### Import with the &lt;import&gt; tag:

```html
<style>
            @import url("https://fonts.googleapis.com/css2?family=Poppins:wght@200;300;400;500;600;700&display=swap");
            * {
                font-family: "Poppins", sans-serif;
                margin: 0;
                padding: 0;
            }
</style>
```

or

### Import with the &lt;link&gt; tag:

```html
<head>
    <meta charset="utf-8">
    <link rel="stylesheet"
          href="https://fonts.googleapis.com/css?family=Tangerine">
    <style>
      body {
        font-family: 'Tangerine', serif;
        font-size: 48px;
      }
    </style>
  </head>
```
# Implementation Guide

This section will help you implement the concepts and best practices outlined in the UX Guidelines.

## Spectrum Design System

Leveraging Spectrum in your add-on allows you to take advantage of all of the built-in benefits it provides while saving front-end development time. There are a few different implementations of Spectrum that are outlined in the sections below for reference, and in order of preferred use.

<InlineAlert slots="text" variant="info"/>

Check out our [code samples](../../samples.md) for examples of how to use the libraries described here. Refer to the **export-sample** and **Pix** sample for a reference on using **Spectrum Web Components**, and the **Dropbox** and **import-images-using-oauth** for specific examples using **React Spectrum**.

### Spectrum Express Theme

If you want your add-on UI to match the [Express look-and-feel](https://spectrum.adobe.com/page/theming/#Resources-for-Spectrum-for-Adobe-Express), you can find Express-themed components available within the [Spectrum CSS](https://github.com/adobe/spectrum-css), [Spectrum Web Components](https://opensource.adobe.com/spectrum-web-components/tools/theme/) and [React Spectrum](https://www.npmjs.com/package/@react-spectrum/theme-express) libraries. Each of the sections below has more details on how to use the theme with the different libraries.

### Icons

Check out the variety of icons available for use in your add-ons from [Spectrum here](https://spectrum.adobe.com/page/icons/) as well. Additionally, there's a set of icons specificlly for the Express theme in an alpha stage currently available. To use those, install the package with `npm i @spectrum-icons/express` and then import the ones you want to use.

## Spectrum Web Components

The [Spectrum Web Components](https://opensource.adobe.com/spectrum-web-components/) project is an implementation of Spectrum with a set of pre-built UI components that can be easily customized and integrated into your application. These components are designed to work seamlessly together and provide a consistent user experience across different devices and platforms. ***We highly recommend Spectrum Web Components as the preferred approach for building the UI of your add-ons***, since it offers a comprehensive set of components and built-in benefits that make it easy to create consistent, accessible, and responsive user interfaces. Some additional benefits include:

  - Framework agnostic
  - Lightweight and performant
  - Standards based

### Spectrum Web Components with React

[**swc-react**](https://opensource.adobe.com/spectrum-web-components/using-swc-react/) is a collection of React wrapper components for the Spectrum Web Components (SWC) library, allowing you to use SWC in your React applications with ease. Currently, `swc-react` supports 62 components. To install `swc-react`, simply replace the scope name `@spectrum-web-components` with `@swc-react` in the package naming convention in your `package.json` (ie: `"@swc-react/button"` instead of `"@spectrum-web-components/button"`). The sub-package name remains identical to the original SWC component and will be automatically installed along with the **swc-react** component. Then, you can import and use it in your `.jsx` like shown in the example below:

```js
import { Button } from "@swc-react/button";

<Button variant="accent">
    Accent Button
</Button>
```

Check out the [swc-react-theme-sampler code sample](../../samples.md#swc-react-theme-sampler) for a specific example of how to use it with various components in your add-on, as well as [the official documentation](https://opensource.adobe.com/spectrum-web-components/using-swc-react/) for more details on **swc-react**.

<InlineAlert slots="text" variant="info"/>

We recommend choosing [**swc-react**](https://opensource.adobe.com/spectrum-web-components/using-swc-react/) over [React Spectrum](#react-spectrum) in your add-ons based on React because it currently offers a more comprehensive set of components and built-in benefits.

### Spectrum Web Components with Express Theme

Below are the steps for using the Express theme with your Spectrum Web Components UI:

- Install the `spectrum-web-components` packages you would like to use. The `theme` package is one you will always want to install, but the others are included for illustration. See the [Spectrum Web Components site](https://opensource.adobe.com/spectrum-web-components/getting-started/) for all of the components available.

    ```bash
    npm install @spectrum-web-components/theme
    npm install @spectrum-web-components/field-label        
    npm install @spectrum-web-components/textfield
    npm install @spectrum-web-components/button
    ```

- Next, start adding your imports. All add-ons should have this base set of imports, which provide support for Spectrum typography and the base Spectrum theme component, the Express themes, including colors (lightest, light, dark, and darkest) and scale options (medium, large).

    ```js
    import '@spectrum-web-components/styles/typography.css';
    import '@spectrum-web-components/theme/sp-theme.js';
    import '@spectrum-web-components/theme/express/theme-darkest.js';
    import '@spectrum-web-components/theme/express/theme-dark.js';
    import '@spectrum-web-components/theme/express/theme-light.js';
    import '@spectrum-web-components/theme/express/theme-lightest.js';
    import '@spectrum-web-components/theme/express/scale-medium.js';
    import '@spectrum-web-components/theme/express/scale-large.js';

    ```

- Then import the specific components you want to use in your code, such as:

    ```js
    import '@spectrum-web-components/button/sp-button.js';
    import '@spectrum-web-components/field-label/sp-field-label.js';
    import '@spectrum-web-components/textfield/sp-textfield.js';
    ```

   **Note:** The `import '@spectrum-web-components/theme/src/express/themes.js';` includes all of the definitions for the Express theme, but you can also only include the specific parts you need. For instance, if you only want to support the light theme and the medium scale, you could specifically include those with: `import '@spectrum-web-components/theme/express/theme-light.js'; import '@spectrum-web-components/theme/express/scale-medium.js';` For more details on themes and all of the color and scale options, see [this link](https://opensource.adobe.com/spectrum-web-components/tools/theme/).

- Use a `webpack.config.js` for bundling the Spectrum Web Components and your JavaScript into a bundle. If you used the basic javascript template for your add-on, you can copy it in from a sample add-on, such as the SWC one in the contributed samples folder. Also be sure to include the webpack specific dependencies and script options in your `package.json`, which you can also copy from a sample like SWC. If you find that some files aren't being moved to `dist` after you build, you'll want to edit the file (line 31,32) to add more file types to copy.

- Now you can use the `scale`, `color` and `theme` selections you desire with the `<sp-theme>` component. Within those tags is where you should place all of your content that you want styled with those settings. For example:

    ```html
    <body>
        <sp-theme scale="medium" color="light" theme="express">   
            /* Everything you want styled with those settings */
            /* goes within the <sp-theme/> tag */
            <sp-field-label required for="txtName">Enter your full name in the field below</sp-field-label>
            <sp-textfield multiline grows id="txtName" placeholder="Full Name"></sp-textfield>
            <sp-button>Submit</sp-button>
        </sp-theme>                    
    </body>
    ```

#### Default vs Express Theme

The screenshots below are from a Spectrum Web Components sample app showing some an example of how the components differ between the themes to illustrate some differences for reference.

#### Default Theme sample:

![Default theme](./img/swc-default-theme.png)

#### Express Theme sample:

![Express theme](./img/swc-express-theme.png)

<InlineAlert slots="text" variant="info"/>

Check out the [code samples](../../samples.md) in the contributed folder for **SWC** and **Pix** for examples of using Spectrum Web Components with plain JavaScript and React accordingly.

## React Spectrum

[React Spectrum](https://react-spectrum.adobe.com/react-spectrum/index.html) is a project that implements the Adobe's Spectrum design language into React UI components.

  React Spectrum is composed of three parts:

  - **react-spectrum**: a component library implementing the Adobe Spectrum design system
  - **react-aria**: a library of React hooks implementing the patterns defined in the ARIA practices spec, including mouse, touch, and keyboard behavior, accessibility, and internationalization support
  - **react-stately**: a library of React hooks implementing cross platform (e.g. web/native) state management for components that need it.

<InlineAlert slots="text" variant="info"/>

We recommend using [**swc-react**](https://opensource.adobe.com/spectrum-web-components/using-swc-react/) over [React Spectrum](#react-spectrum) in your add-ons based on React, because it currently offers a more comprehensive set of components which provide built-in benefits as detailed above in the [Spectrum Web Components section](#spectrum-web-components), and is more actively supported.

### React Spectrum with Express Theme

[The React Spectrum Express theme](https://www.npmjs.com/package/@react-spectrum/theme-express) is still in an alpha stage currently, but can be used with the following steps:

1. Install it in your project with:

    `npm install @react-spectrum/theme-express`

2. Install the Express themed icons:

    `npm install @spectrum-icons/express`

3. Import the theme and icons into your code to use them. For example, notice the following code snippet which imports and sets the Express `theme`, light `colorScheme` option and medium `scale` option on the `<Provider>` object. It also illustrates how to use the Express version of the `Delete` icon.

    ```js
    import { theme as expressTheme } from '@react-spectrum/theme-express';
    import Delete from '@spectrum-icons/express/Delete';

    const App = ({ addOnUISdk }) => {
        return (
            <Provider theme={expressTheme} colorScheme="light" scale="medium">
                <Button variant="accent"><Delete/></Button>  
            </Provider>       
        )
    }
    ```

#### React Spectrum Theme Examples

Below is an example of some components from React Spectrum with the two themes. Please note, since the [React Spectrum with Express theme project](https://www.npmjs.com/package/@react-spectrum/theme-express) is still in an alpha state, there will be components that haven't been completely ported over yet.

##### Default theme sample:

![Default theme](./img/default-theme.png)

##### Express theme sample:

![Express theme](./img/express-theme.png)

<InlineAlert slots="text" variant="info"/>

The [React Spectrum Express theme](https://www.npmjs.com/package/@react-spectrum/theme-express) is still in an alpha state, but you can use [Spectrum Web Components](https://opensource.adobe.com/spectrum-web-components/tools/theme/) with React as well. See the **Pix** code sample in the provided samples for an example of how to mix Spectrum Web Components with React. Specifically, you should note that there are some intricacies when using this combination of Spectrum Web Components and React in terms of event handling, but they can be handled by using a component that wraps the Spectrum Web Components for providing the event handling instead. In the **Pix** sample, take a look at the wrapper component called `WC.jsx` for a reference of how to do this.

#### CAUTION: Using React Spectrum with a Slider Component

If you're using a slider component with React Spectrum, you may notice behavior where if the user moves their mouse out of the panel and releases the mouse pointer, the slider still thinks the mouse pointer is down when the mouse is moved back inside the panel. You can fix this with the following steps:

1. Wrap your slider(s) with another element. A &lt;div&gt; works fine.
2. Add a ref that points to this div so you can refer to it later.
3. Add two event handlers:
    - `onPointerDownCapture` will call `sliderContainer.current.setPointerCapture(evt.nativeEvent.pointerId)`
    - `onPointerUp` will call `sliderContainer.current.releasePointerCapture(evt.nativeEvent.pointerId)`

**Example Snippet**

```js
import React, {useRef} from "react";

import { theme as expressTheme } from '@react-spectrum/theme-express';
import {Slider, Provider} from '@adobe/react-spectrum'

const App = ({ addOnUISdk }) => {
    const sliderContainer = useRef();
    const startDrag = (evt) => {
        sliderContainer.current.setPointerCapture(evt.nativeEvent.pointerId);
    }
    const stopDrag = (evt) => {
        sliderContainer.current.releasePointerCapture(evt.nativeEvent.pointerId);
    }
    return <>
        <Provider theme={expressTheme} colorScheme="light" scale="medium">
            <div ref={sliderContainer} onPointerDownCapture={startDrag} onPointerUp={stopDrag}>
                <Slider label="Cookies to buy" defaultValue={12} />
            </div>
        </Provider>
    </>
};

export default App;
```

## Spectrum CSS

[Spectrum CSS](https://opensource.adobe.com/spectrum-css/) is an open-source implementation of Spectrum and includes components and resources to make applications more cohesive. Spectrum CSS is designed to be used in partnership with [Spectrum’s detailed usage guidelines](https://spectrum.adobe.com/).

<InlineAlert slots="text" variant="warning"/>

You should only rely on using the base [Spectrum CSS](https://opensource.adobe.com/spectrum-css/) library for simple applications that need basic things like typography, checkboxes, text fields, etc. Otherwise you should try using one of the other implementations provided like [Spectrum Web Components](https://opensource.adobe.com/spectrum-web-components/) and [React Spectrum](https://react-spectrum.adobe.com/react-spectrum/index.html) since they include interactivity, event handling etc built-in over what's possible with pure CSS. The best place to start with each of these libraries is to go to the **Getting Started** page in the top of the docs for each.

## Tips

Use the existing Adobe Express UI as an example of the types of patterns and behaviors to use in your own add-on design. For instance, you could take a closer look at the other panels and how the UI is implemented in them to help guide you, such as the Media, Theme and Text panels shown below, which are already part of Express.

#### Media Panel

![Express Media Panel](img/media-panel.png)

#### Theme Panel

![Express Theme Panel](img/theme-panel.png)

#### Text Panel

![Express Text Panel](img/text-panel.png)

<InlineAlert slots="text" variant="success"/>

**Color Picker Component Tip:**
If you're using the native browser color picker, it looks slightly different in every browser and doesn't fit the Express theme by default. You can make this control look more like Spectrum with CSS as [illustrated in this codepen](https://codepen.io/kerrishotts/pen/QWZazJP) for reference, or borrow the code used in [this guide](../tutorials/grids-addon.md#coding-the-grids-add-on).

## Using Fonts

The following `adobe-clean` fonts and weights are injected into the add-on and can be used automatically.

```css
{
    family: "adobe-clean",
    source: "url('https://use.typekit.net/af/c0160f/00000000000000007735dac8/30/l?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n4&v=3') format('woff2'), url('https://use.typekit.net/af/c0160f/00000000000000007735dac8/30/d?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n4&v=3') format('woff'), url('https://use.typekit.net/af/c0160f/00000000000000007735dac8/30/a?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n4&v=3') format('opentype')",
    weight: "400",
    style: "normal",
    display: "auto"
},
{
    family: "adobe-clean",
    source: "url('https://use.typekit.net/af/95bf80/00000000000000007735dacd/30/l?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=i4&v=3') format('woff2'), url('https://use.typekit.net/af/95bf80/00000000000000007735dacd/30/d?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=i4&v=3') format('woff'), url('https://use.typekit.net/af/95bf80/00000000000000007735dacd/30/a?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=i4&v=3') format('opentype')",
    weight: "400",
    style: "italic",
    display: "auto"
},
{
    family: "adobe-clean",
    source: "url('https://use.typekit.net/af/5c07ba/00000000000000007735dad8/30/l?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n7&v=3') format('woff2'), url('https://use.typekit.net/af/5c07ba/00000000000000007735dad8/30/d?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n7&v=3') format('woff'), url('https://use.typekit.net/af/5c07ba/00000000000000007735dad8/30/a?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n7&v=3') format('opentype')",
    weight: "700",
    style: "normal",
    display: "auto"
},
{
    family: "adobe-clean",
    source: "url('https://use.typekit.net/af/2dda0a/00000000000000007735dad4/30/l?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n8&v=3') format('woff2'), url('https://use.typekit.net/af/2dda0a/00000000000000007735dad4/30/d?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n8&v=3') format('woff'), url('https://use.typekit.net/af/2dda0a/00000000000000007735dad4/30/a?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n8&v=3') format('opentype')",
    weight: "800",
    style: "normal",
    display: "auto"
},
{
    family: "adobe-clean",
    source: "url('https://use.typekit.net/af/bc79c1/00000000000000007735dad9/30/l?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n9&v=3') format('woff2'), url('https://use.typekit.net/af/bc79c1/00000000000000007735dad9/30/d?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n9&v=3') format('woff'), url('https://use.typekit.net/af/bc79c1/00000000000000007735dad9/30/a?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n9&v=3') format('opentype')",
    weight: "900",
    style: "normal",
    display: "auto"
}
```

### Importing custom fonts

You can use a custom font with a URL by either linking to it via the `@import` rule, the &lt;link&gt; tag, or the `@font-face` rule.

#### Via the `@import` rule:

```css
<style>
    @import url("https://fonts.googleapis.com/css2?family=Poppins:wght@200;300;400;500;600;700&display=swap");
    * {
        font-family: "Poppins", sans-serif;
        margin: 0;
        padding: 0;
    }
</style>
```

#### Via the `<link>` tag:

```html
<head>
    <meta charset="utf-8">
    <link rel="stylesheet"
          href="https://fonts.googleapis.com/css?family=Tangerine">
    <style>
      body {
        font-family: 'Tangerine', serif;
        font-size: 48px;
      }
    </style>
  </head>
```

#### Via the `@font-face` rule

Specify a name for the font and where it can be found, then use it on the desired HTML tag with the specified name. For example:

```css
@font-face {
  font-family: "MyWebFont";
  src: url("https://mdn.github.io/css-examples/web-fonts/VeraSeBd.ttf");
}
body {
  font-family: "MyWebFont", serif;
}
```

<InlineAlert slots="text" variant="warning"/>

Using custom fonts can be great for design, but it’s important to also understand that it can can cause a performance hit because the font must be downloaded before it’s displayed. Note that the `@font-face` `src:` supports a `local` attribute as well which will try to load the font from the users local system first, which can help mitigate the performance hit. See [this link](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face) for full details.

## Useful Resources

- [Figma plugin](https://www.figma.com/community/file/1211274196563394418/Adobe-Spectrum-Design-System) that provides Spectrum UI elements.
---
hideBreadcrumbNav: true
---

# Design Overview

The design of your add-on is just as important to the success of your add-on as the features it provides.

## Introduction

This set of design guides is provided to help lead you through the design process of your add-on and includes useful guidelines, tips, and resources. First, we encourage you to watch this short video about designing your add-on interface, then read on for more details. <br/><br/>

<div style="display: flex; justify-content: center;">
    <iframe width="560" height="315" src="https://www.youtube.com/embed/E9atPm5djco?si=QbafmhPAKJa6R4rI" title="Designing Add-on Interfaces" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>  
</div>
---
keywords:
  - Adobe Express
  - Express Add-on 
  - Extend
  - Extensibility
  - User Interface
  - User Experience
  - UI
  - UX
  - Guidelines
  - Branding
title: Branding Guidelines
description: This document provides an overview of the UX guidelines to follow when designing your Adobe Express add-on.
contributors:
  - https://github.com/undavide
---

# Branding Guidelines

When creating your add-on, a distinct and consistent brand identity is your ticket to a lasting impression.

This section focuses on key aspects of branding, like Icon and Publisher Logo design, as well as best practices for incorporating promotional images (screenshots or illustrations) for the Adobe Express add-on Marketplace.

Please refer to the [Developer Brand Guidelines](https://developer.adobe.com/express/embed-sdk/docs/assets/34359598a6bd85d69f1f09839ec43e12/Adobe_Express_Partner_Program_brand_guide.pdf) for comprehensive details on integrating Adobe branding, including when and how to use Adobe logos, product names, and terms.

## Add-on Icon

The add-on's icon should be original, suitable for different devices and browsers, and not violate the [Developer Brand Guidelines](https://developer.adobe.com/express/embed-sdk/docs/assets/34359598a6bd85d69f1f09839ec43e12/Adobe_Express_Partner_Program_brand_guide.pdf). Please request a written license agreement from Adobe if you wish to use any Adobe logo, product icon, or image in your preview and feature graphics, product icons, or website.

Three sizes are required for the add-on's icon: **36x36**, **64x64**, and **144x144** pixels as PNG or JPG files.

![add-on icon](./img/branding_add-on-icon.png)

## Publisher Logo

The publisher's logo is only required the first time you [submit for distribution](/guides/distribute/public-dist.md#2-prepare-your-assets), in case you've never created a publisher profile before. It should be a square, **250x250** pixels PNG or JPG file.

![publisher logo](./img/branding_publisher-logo.png)

## Imagery

When creating a [public listing](../../distribute/public-dist.md) for the Adobe Express add-on Marketplace, you can provide promotional images, such as screenshots and illustrations. At least one is required.

![screenshots and illustrations](../../distribute/img/public-listing-screenshots-v2.png)

### Screenshots and illustrations

Any image used in your listing must comply with the [Developer Brand Guidelines](https://developer.adobe.com/express/embed-sdk/docs/assets/34359598a6bd85d69f1f09839ec43e12/Adobe_Express_Partner_Program_brand_guide.pdf). They should accurately depict the add-on's functionality and features and not contain any misleading information or inappropriate content. The recommended image size is **1360x800** pixels, as PNG or JPG.

![screenshots and illustrations](./img/branding_screenshot.png)
---
keywords:
  - Adobe Express
  - Express Add-on 
  - Extend
  - Extensibility
  - User Interface
  - User Experience
  - UI
  - UX
  - Guidelines
  - Branding
title: Changelog
description: UX Guidelines Changelog.
contributors:
  - https://github.com/undavide
---

## Changelog

### 8 October 2024

- Created a new web version of the Adobe Express add-on UX Guidelines.
- Integrated the existing content from the Adobe XD document into the new structure. The old version is [available here](https://xd.adobe.com/view/urn:aaid:sc:US:fd638450-1af8-49c3-ad29-0e76c2a2136f/) as a reference.

### 28 August 2023

- Last update to the Adobe XD document version of the Adobe Express add-ons UX Guidelines.
---
keywords:
  - Adobe Express
  - Express Add-on
  - Extend
  - Extensibility
  - User Interface
  - User Experience
  - UI
  - UX
  - Guidelines
  - Design Principles
title: Design Principles
description: This document provides an overview of the UX guidelines to follow when designing your Adobe Express add-on.
contributors:
  - https://github.com/undavide
---

# Design Principles

When you're designing add-ons for Adobe Express, it's important to start with the principles that guide all of Adobe's products. They will be your roadmap, ensuring that what you create is not only visually appealing but also consistent, accessible, and user-friendly. Think of them as your toolkit for building something that looks great, works well, and fits seamlessly into the application.

## Consistency: creating a cohesive experience

You should design your add-ons to feel like a natural extension of the platform, conforming to Adobe Express's visual language: the Spectrum Design System. This coherence isn't just about visual elements but extends to interaction patterns and behaviours. Keeping everything aligned creates a smoother experience where users can easily navigate and understand your add-on, achieving their goals effortlessly.

## Accessibility: designing for inclusion

All add-ons you develop should be accessible to everyone, regardless of their abilities or circumstances. This includes considering elements like contrast and text size, as well as accommodating a broad spectrum of digital skills. An accessible design adapts to the user, offering clear and intuitive interactions, removing barriers, and making sure that every user can fully engage with it.

## Usability: prioritizing ease of use

Your add-on should be as easy to operate as it is powerful. Design it with users in mind so they can navigate it effortlessly, where each feature is clearly accessible and straightforward. Eliminate unnecessary steps and ensure that every interaction feels natural. Always provide feedback so users know what to expect and how to achieve their goals. The more intuitive the experience, the more likely they are to engage and rely on it over again.

## Aesthetics: balancing form and function

The aesthetic appeal of your add-on plays a significant role in the overall user experience: a pleasing design attracts more users and enhances their interaction with it. When the design is functional and visually charming, it creates an enjoyable experience and complements usability. Keeping the aesthetics aligned with Adobe's brand identity will reinforce the connection to the platform and tighten the overall user experience.

## Bringing it all together

By embracing these design principles, you'll build add-ons that integrate smoothly with Adobe Express and provide real value to users. Each concept works in harmony with the others; keep these guidelines in mind as you develop, and you'll create tools that are both effective and a pleasure to use. In the following pages, you'll find detailed recommendations, requirements, and best practices to help you apply these principles to your projects.
---
keywords:
  - Adobe Express
  - Express Add-on 
  - Extend
  - Extensibility
  - User Interface
  - User Experience
  - UI
  - UX
  - Guidelines
  - Feedback
  - Messaging
title: Feedback & Messaging
description: This document provides an overview of the UX guidelines to follow when designing your Adobe Express add-on.
contributors:
  - https://github.com/undavide
---

# Feedback & Messaging

Feedback and messaging are essential UX components. Your add-ons should always provide users with information about the state of the system, the results of their actions, and any errors that may have occurred.

Unclear feedback and mishandled errors can lead to confusion and, crucially, are a cause of [rejection](../../../guides/distribute/rejections.md#error-handling) when submitting add-ons to the Adobe Express Marketplace. On the other hand, well-designed feedback can help users understand what is happening and what they need to do next.

## Loading Indicators

Loading indicators are particularly important when the system is processing a request that may take some time to complete; for instance, when fetching data from a server or authenticating a user. They show that the system is working and users should wait for the process to finish.

### Progress Circles

[Progress circles](https://spectrum.adobe.com/page/progress-circle/) show the progression of a system operation such as downloading, uploading, processing, etc. in a visual way.

![Progress circles](./img/feedback_progress-circles.png)

They can represent determinate or indeterminate progress: either the percentage of the operation that has been completed or spin indefinitely until completion.

![](./img/feedback_progress-circles-animation-wide.gif)

### Ghost Loading

When a group of cards are loading, they follow the [ghost loading convention](https://spectrum.adobe.com/page/cards/#Ghost-loading).

![](./img/feedback_ghost-loading.png)

There are 5 phases for ghost loading:

1. Card group (including metadata) ghost loads.
2. If metadata for all cards is loaded before all preview images are loaded, the metadata is displayed for all cards as soon as the last piece of metadata loads. Previews continue to ghost-load.
3. If all preview images load within a certain period (usually measured in seconds, which you need to specify depending on the use case), they are shown as soon as the last preview loads.
4. If all previews have not finished loading at the end of the x period, the loaded previews are shown, and the pending previews each receive an individual progress circle. The group is no longer in a ghost-loading state.
5. If the preview load times out, an error is shown along with a mechanism to retry loading.

## In-line Alerts

[In-line alerts](https://opensource.adobe.com/spectrum-css/inlinealert.html) display a non-modal message associated with objects in a view. These are often used in form validation, providing a place to aggregate feedback related to multiple fields.

![](./img/feedback_ghost-loading.png)

## Toasts

[Toasts](https://spectrum.adobe.com/page/toast/) display brief, temporary notifications. They’re meant to be noticed without disrupting a user’s experience or requiring an action to be taken.

![](./img/feedback_toasts.png)

They come in multiple kinds, each with a different purpose:

![](./img/feedback_toast-kinds.png)

## Full-panel Messaging

When the feedback is more complex or requires more space, a full-panel message can be used.

![](./img/feedback_full-panel-messaging.png)

Please mind the padding between the graphics, text and other UI elements to ensure a clear and organized layout.

![](./img/feedback_full-panel-messaging-padding.png)
---
keywords:
  - Adobe Express
  - Express Add-on 
  - Extend
  - Extensibility
  - User Interface
  - User Experience
  - UI
  - UX
  - Guidelines
hideBreadcrumbNav: true
title: Add-on UX Guidelines
description: This document provides an overview of the UX guidelines to follow when designing your Adobe Express add-on.
contributors:
  - https://github.com/undavide
---

# UX Guidelines for Adobe Express Add-ons

A successful add-on provides a seamless and intuitive User Experience (UX) that blends harmoniously with Adobe Express.

![](./img/introduction_cover.png)

These Guidelines are your roadmap to creating add-ons that align with Adobe's design principles and visual language, ensuring a consistent and enjoyable experience. Following them will help you build tools that resonate with users and feel like a natural extension of the application.

## Intended audience

This document is intended for developers, designers, and product teams involved in creating Adobe Express add-ons. Whether you're crafting your first add-on or improving an existing one, these guidelines offer valuable insights and best practices to help you align with Adobe's UX standards.

## How to navigate this document

To get the most out of the UX Guidelines, start by familiarizing yourself with the [Design Principles](design_principles.md) section. They provide the foundation for all design decisions and will help you understand the core values that should drive your work.

Next, the [Theming](theming.md) section shows you how to implement the Spectrum for Adobe Express theme, along with customization options and examples. [Visual Elements](./visual_elements.md) is a detailed list of structural and functional components that make up the Adobe Express visual language. It covers everything from typography to grids, navigation, and a variety of UI elements alongside with implementation examples.

[Feedback & Messaging](feedback_and_messaging.md) provides best practices for communicating feedback or alert errors to users.

<!-- The [Mobile UX](mobile_ux.md) section offers guidance on how to format content for mobile devices so that the user experience is consistent across all platforms. -->

Explore the [Branding Guidelines](branding_guidelines.md) to ensure your add-on is legally & visually aligned with Adobe Express. They cover key aspects of branding, as well as best practices for incorporating promotional images for the Adobe Express add-on Marketplace.

Finally, look at the [Resources & References](./resources_and_references.md) for videos and further reading. Refer to the [Changelog](./changelog.md) to stay up-to-date with the latest features and improvements to these guidelines: they are a living document we encourage you to consult regularly, both as a reference and a source of inspiration.
---
keywords:
  - Adobe Express
  - Express Add-on 
  - Extend
  - Extensibility
  - User Interface
  - User Experience
  - UI
  - UX
  - Guidelines
  - Mobile
title: Mobile UX
description: This document provides an overview of the UX guidelines to follow when designing your Adobe Express add-on.
contributors:
  - https://github.com/undavide
---

# Mobile UX

Designing add-ons that can be used when Adobe Express runs on mobile devices requires some attention. Although the same general principles so far outlined still apply, component sizing, layout, and typography should be tweaked to ensure the proper user experience on smaller screens.

The following sections outline the key differences and best practices for optimizing your add-ons for mobile devices.

![Mobile UX overview](./img/mobile_overview.png)

## Basic Structure

Mobile interfaces feature a streamlined layout, with two primary content areas controlled by Adobe: the title bar and the footer. The add-on's content is displayed in the body area; considering the smaller screen size, you should optimize the design for readability and ease of interaction.

![Mobile basic structure](./img/mobile_basic-structure.png)

## Default panel height vs. full panel height

By default, the panel covers around half of the screen's vertical space, with a height of 375px. This layout balances the add-on interface and the document view, ensuring both are easily accessible.

When the user swipes up the handlebar, which is always visible, the panel expands upward until the entire 699px height available is covered. This full-height view is ideal for displaying detailed content or additional options.

![Mobile height](./img/mobile_default-vs-full.png)

## Typography

Typography on mobile requires adjustments from desktop standards to ensure readability; the font size is generally smaller, and the weight is lighter.

For **headings**, we recommended a font-size in the 15-19px range, and not exceeding 20px. The font-weight should be 400-500, typically the latter. On desktop, headings are in the 14-22px range (rarely, up to 34px) and weights of 600-700 are common.

![Mobile typography](./img/mobile_typography.png)

On mobile, **body** is in the same 15-19px range, with a font-weight of 300.

![Mobile typography specs](./img/mobile_typography-specs.png)

## Foundational components

While mobile and desktop share many common components, sizing and placement are crucial distinctions. Mobile interfaces should avoid using extra-large (XL) component instances, which can overwhelm the screen. Instead, opt for Medium (M) or Large (L) sizes, more suitable for mobile displays.

![Mobile foundational components](./img/mobile_components.png)

### Buttons

On mobile, buttons that convey singular, primary actions should be styled using the Medium size and Primary variant. Center them horizontally and align them to the bottom—remember to account for the footer area controlled by Adobe.

![Mobile buttons](./img/mobile_buttons.png)

### Button Groups

Button groups should extend across the available width of the UI, minus a 40px margin (16px on each side, with an 8px gap between buttons). This layout ensures that buttons are easily tappable and well-spaced on smaller screens.

![Mobile buttons](./img/mobile_button-groups.png)
---
keywords:
  - Adobe Express
  - Express Add-on 
  - Extend
  - Extensibility
  - User Interface
  - User Experience
  - UI
  - UX
  - Guidelines
  - Resources
  - References
title: Resources and References
description: This document provides an overview of the UX guidelines to follow when designing your Adobe Express add-on.
contributors:
  - https://github.com/undavide
---

# Resources and References

To inform and inspire your design process, we've compiled a list of resources and references to help you create engaging, consistent and functional user experiences for your Adobe Express add-ons.

## Video Tutorials

Design tips for creating Adobe Express add-ons, by Steph Corrales (Sr. Experience Designer, Adobe Developer Experience).

<br/><br/><div style="display: flex; justify-content: center;">
 <iframe width="560" height="315" src="https://www.youtube.com/embed/siWxy4BwkIE?si=LSjjwF1W0JNziDMg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
</div><br/>

Adobe Express add-on's with Spectrum Web Components [workshop](../../tutorials/spectrum-workshop/index.md), by Holly Schinsky (Sr. Developer Relations Engineer, Adobe Developer Experience).

<br/><br/><div style="display: flex; justify-content: center;">
<iframe width="560" height="315" src="https://www.youtube.com/embed/5PA4KEN4JdQ?si=vcJRsJNx948VFd3l" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
</div><br/>

<!-- ## Tools and Templates

**TODO:** Ask the Design team to provide a list of resources they would like to include here. -->

## Further Reading

- [Adobe Spectrum](https://spectrum.adobe.com/): Adobe's design system.
- [Spectrum Web Components](https://opensource.adobe.com/spectrum-web-components/): Web components implementation of Spectrum.
- [Adobe Spectrum 2](https://s2.spectrum.adobe.com/): the next major version of Spectrum, currently in preview.

<!-- ## Acknowledgments

**TODO:** Ask the Design team what content is supposed to go here. -->
---
keywords:
  - Adobe Express
  - Express Add-on 
  - Extend
  - Extensibility
  - User Interface
  - User Experience
  - UI
  - UX
  - Guidelines
  - Theming
title: Theming
description: This document provides an overview of the UX guidelines to follow when designing your Adobe Express add-on.
contributors:
  - https://github.com/undavide
---

# Theming

Adobe Express is based on Spectrum, Adobe's design system, which provides a set of guidelines and components for creating consistent and visually engaging user interfaces.

While Spectrum is the main reference throughout this guide, the Adobe Design team has released a preview of the next major version, [Spectrum 2](https://s2.spectrum.adobe.com/): a completely rebuilt user experience that is more modern, friendly, accessible, and enjoyable to use.

## Spectrum for Adobe Express Theme

The Spectrum design system supports theming, allowing you to customize features like icon sets, font weight and size, and accent colors to suit your brand or use case better. We recommend using the provided [Adobe Express Theme](https://spectrum.adobe.com/page/theming/#Available-themes), specifically designed to accommodate the needs of a mainstream, creative consumer audience. It features a friendlier visual tone, bolder typography, softer rounding on elements, and indigo as the accent color. See the Spectrum for Adobe Express theme in action below on the right, compared to the default on the left:

![Spectrum for Adobe Express](./img/components_theme.png)

## Customization Guidelines

When customizing your add-on's theme, you're free to incorporate brand-specific elements, such as color schemes and logos tailored to your identity. It is essential that the overall experience remains consistent with the Spectrum for Adobe Express styling guidelines, though. They ensure a cohesive user experience across all add-ons, maintaining a professional and polished appearance while allowing room for personalization.

If you’re developing a custom component, it must adhere to the Spectrum Express style standards, too, in order to ensure visual harmony and usability within the Adobe Express ecosystem. For detailed guidance on these requirements, please refer to [these guidelines](https://opensource.adobe.com/spectrum-web-components/tools/theme/#usage).

<!-- ## Theming Examples

**TODO:** Same as above. -->
---
keywords:
  - Adobe Express
  - Express Add-on 
  - Extend
  - Extensibility
  - User Interface
  - User Experience
  - UI
  - UX
  - Guidelines
  - Visual Elements
title: Visual Elements
description: This document provides an overview of the UX guidelines to follow when designing your Adobe Express add-on.
contributors:
  - https://github.com/undavide
---

import '/src/styles.css'

# Visual Elements

You can use Color, Typography and Layout to establish hierarchy in your designs.

Adobe Express implements the "Spectrum for Adobe Express theme", which has been designed specifically for it. You’ll notice a friendlier visual tone, with bolder typography, softer rounding on elements, and indigo serving as the accent color.

## Color

The colors available in the Spectrum for Adobe Express light theme are designed to provide users with clear visual context and establish a hierarchy of actions within the UI. These colors help guide users through their workflow, ensuring that key actions stand out while maintaining a cohesive and accessible design.

When applying color, follow the specific styling recommendations at the component level to ensure consistency. Avoid overusing the accent color: it's meant to highlight primary actions, not dominate the entire interface. Additionally, adhere to the contrast ratio guidelines to maintain readability and accessibility for all users.

For more details on best practices, please refer to this [Color system guide](https://spectrum.adobe.com/page/color-system/#Colors).

## Typography

Spectrum is based on the Adobe Clean and Adobe Clean Han typefaces. The former is used for Latin characters, while the latter is for Simplified Chinese, Traditional Chinese, Japanese, and Korean ones.

<!-- <div className="container">
  <div className="image-column">
    <img src="./img/visual_heading.png" alt="headings" className="responsive-image" />
  </div>
  <div className="text-column">
    <h3>Headings</h3>
    <p>Headings in Spectrum for Adobe Express always use bolder typography. The default and heavy weights both rely on Adobe Clean Black (Sans Serif).</p>
  </div>
</div> -->

### Headings

Headings in Spectrum for Adobe Express use bolder typography. The default weight is 700 (Adobe Clean Black, Sans Serif), with a size ranging from M to XXS.

![](./img/visual_heading.png)

### Body Text

The available sizes for body text in Spectrum for Adobe Express span from XS to XXL, while the weight is usually around 400-500.

![](./img/visual_body.png)

### Usage

Here's an example of how you can implement the Adobe Clean typeface in your add-on; please note the recommended spacing between text and other user interface elements.

![](./img/visual_example.png)

## Layout & Structure

A well-structured layout sets the stage for a great design.

Adobe Express is built on a clean and consistent structure designed for clarity and usability: add-ons should follow the same rules and blend in.

### Basic Structure

Add-ons on Desktop are assigned a specific width of **320px** and a **100%** height to ensure uniformity within the Adobe Express user interface and its modules. The layout is divided into the following parts:

- The title bar with the add-on's icon—controlled by Adobe.
- The body holding the add-on's content.
- Optionally, a footer with Call to Action (CTA) buttons.

![Basic Structure](./img/layout_basic.png)

### Padding

Padding plays a crucial role in maintaining visual harmony and readability. You should consistently apply the following padding scheme:

- **24px** on the body to create a balanced spacing around the content. An additional padding of the same amount is applied at the footer's bottom.
- **16px** between internal elements to ensure they are appropriately spaced.

This padding structure ensures that content is well-separated and easy to interact with.

![Padding](./img/layout_padding.png)

### Responsive Grid and Core Container Styles

Adobe Express add-ons rely on a [responsive grid system](https://spectrum.adobe.com/page/responsive-grid/). Core container styles define a few key media sizes:

- **272x128px** for banners.
- **128x128px** tops for standard media.
- **80x80px** for smaller media items.

Remember to apply the standard gap of 16px between grid elements for consistency.

![Responsive Grid and Core Container Styles](./img/layout_grid.png)

### Panel Structure and core content actions

Panel structure in Adobe Express add-ons is designed to support core content actions, such as searching, sorting, and filtering. These actions are typically placed at the top of the panel for easy access, between the title and main body.

![Panel Structure and core content actions](./img/layout_actions.png)

### Structural Grids and Foundational Patterns

Structural grids in Adobe Express add-ons are designed to accommodate various content types, from simple lists to more visually complex media grids. Three of the container variants are as follows:

- **Media Grid:** A straightforward grid for displaying media items.
- **Media Grid with Labels:** Enhances the basic grid by adding labels beneath each item, ensuring clarity.
- **Media Grid with Cards:** Adds a card-like structure on each media item.

Please note the specific paddings on each of these grid types.

![Structural Grids and Foundational Patterns](./img/layout_patterns.png)

## Panel Actions

Panel Actions are interactive elements that allow users to search, sort, filter, and manage content within your add-on.

### Actions Overview

Commonly found at the top of the add-on panel, Panel Actions include:

- **Search**: allows users to quickly find specific content.
- **Filter**: enables users to narrow down visible content based on criteria.
- **Sort**: organizes content by relevance, date, or other metrics.
- **Add Folder**: gives users the ability to create new folders within the add-on.
- **Tabs**: lets users navigate between different sections or views.

These actions enable users to "drill into" specific sections, for example dynamically refining a list of thumbnails that follows.

![Panel Actions](./img/visual_actions-search.png)

### Best Practices

Panel Actions, when available, should be arranged at the top of the add-on's content area. This ensures that users can easily access them and that they are always visible even when the grid below scrolls.

### Examples

Here are some examples of common panel organizations and hierarchies for Adobe Express add-ons.

![Examples](./img/visual_actions.png)

## Components

Spectrum includes a number of widgets that allow you to build rich UIs for your add-ons. Foundational components should use the Spectrum for Adobe Express theme whenever possible.

This is a [Spectrum theme](https://spectrum.adobe.com/page/theming/) specifically designed for the Adobe Express product suite to accommodate the needs of a mainstream, creative consumer audience. It features a friendlier visual tone, bolder typography, softer rounding on elements, and indigo as the accent color. See the Spectrum for Adobe Express theme in action below on the right, compared to the default on the left:

![Spectrum for Adobe Express](./img/components_theme.png)

<!-- ### Buttons & Buttons Groups

Buttons are essential for enabling user interactions in your add-on. -->

### Buttons

[Buttons](https://spectrum.adobe.com/page/button/#Usage-guidelines) allow users to perform an action or navigate to a different part of the add-on. They have multiple styles to fit various needs and are ideal for calling attention when a user needs to take action to move forward in the workflow.

![Buttons](./img/components_buttons.png)

Please mind the padding when using CTA buttons in the add-on's footer.

### Button Groups

A [Button Group](https://spectrum.adobe.com/page/button-group/) is a collection of buttons that perform related actions. See the [Usage Guidelines](https://spectrum.adobe.com/page/button-group/#Usage-guidelines) for more information on their correct use.

![Button Groups](./img/components_button-groups.png)

### Secondary Variant Buttons

The [Secondary Variant Button](https://spectrum.adobe.com/page/button/#Usage-guidelines) is for low emphasis. It’s paired with other button types to surface less prominent actions, and should never be the only button in a group.

![Button Groups](./img/components_secondary-button-variants.png)

Spectrum buttons support several variants (Accent, Primary, Secondary, Negative, Icon) to fit different use cases; refer to the [Spectrum reference](https://spectrum.adobe.com/page/button/#Options) to see all available options and when to use them.

## Form Elements

Form elements are essential for collecting user input and enabling interactions within your add-on. They include a variety of components such as text fields, search fields, pickers, and more.

### Text Fields

[Text fields](https://spectrum.adobe.com/page/text-field/) allow users to input custom text entries with a keyboard. Various options can be shown with the field to communicate their requirements.

![Text Fields](./img/form_text-fields.png)

It's recommended to let text fields span the entire add-on's width—minus the container's padding—when possible, for a more consistent look.

### Search Fields

A [Search Field](https://spectrum.adobe.com/page/search-field/) is used for searching and filtering content. As mentioned in the [Layout & Structure](#layout--structure) section, the search field should be placed at the top of the panel, between the title and the main body.

![Search Fields](./img/form_search-field.png)

### Pickers

[Pickers](https://spectrum.adobe.com/page/picker/) (sometimes known as "dropdowns" or "selects") allow users to choose from a list of options in a limited space. The list of options can change based on the context.

![Pickers](./img/form_pickers.png)

Like all the components covered so far, it's best for pickers to take advantage of the add-on's full width.

### Color Pickers

Color pickers are a special type of picker that allows users to select a color.

![Color Pickers](./img/form_color-pickers.png)

The Spectrum component used as a Color Picker is the [Swatch](https://spectrum.adobe.com/page/swatch/), which shows a small sample of a fill—such as a color, gradient, texture, or material—that is intended to be applied to an object.

The Swatch itself doesn't embed any color picker functionality, but it can be used in conjunction with a native `<input>` hidden element to trigger the browser's color picker. You can find an example with sample code in [this tutorial](/guides/tutorials/grids-addon.md#coding-the-grids-add-on).

## Navigation

Navigation is a key component of any user interface. It helps users understand where they are, where they can go, and how to get there. Spectrum provides a few components that we recommend to help you build a clear and consistent navigation system for your add-on.

### Tabs

Tabs organize content into multiple sections and allow users to navigate between them; the content under the set of tabs should be related and form a coherent unit. Please always include a label for accessibility.

![Tabs](./img/navigation_tabs.png)

### Accordions

The [Accordion](https://opensource.adobe.com/spectrum-web-components/components/accordion/) element contains a list of items that can be expanded or collapsed to reveal additional content or information associated with each item. There can be zero expanded items, exactly one expanded item or more than one item expanded at a time, depending on the configuration. This list of items is defined by child elements that are targeted to the default slot of their parent.

![Accordions](./img/navigation_accordions.png)
# Cross-origin isolation handling

How to ensure your add-ons work properly with the cross-origin isolation headers enforced by Adobe Express.

## Overview

Adobe Express will soon be enforcing cross-origin isolation on the associated domains (i.e., “new.express.adobe.com”) for Chromium-based browsers (including Chrome, Microsoft Edge, Opera, and others). This *may* impact your add-on due to stricter rules enforced by the browser.

<InlineAlert slots="text" variant="info"/>

We expect the enforcement of cross-origin isolation headers to begin around the end of 2024, and we will update you the moment we have a more specific date. In the meantime, you’ll want to ensure that any add-ons you’ve developed or are developing now work in this new environment.

Specifically, Adobe Express will be setting the following response headers:

- `Cross-Origin-Embedder-Policy: credentialless`
- `Cross-Origin-Opener-Policy: same-origin`
- `Cross-Origin-Resource-Policy: same-site`

This change is being done to support Adobe Express’ use of certain browser capabilities requiring cross-origin isolation.

## Impact

This change may impact your add-on’s access to external resources, especially if it relies on iframes to display content or support payment flows. It could also impact  `fetch` or image requests from external sources. In these cases, users may see missing content or be presented with silent failures if your add-on can’t load a remote resource. Since this results in a poor experience, developers must ensure that their add-ons work in the above environment.

Please note that this change affects *all* add-ons, even those not published in the add-on marketplace (i.e., private and internally distributed add-ons).

Currently, this change *only impacts* Chromium-based browsers (e.g., Chrome, Edge, Opera, etc.). Firefox and Safari browsers are currently exempt. If you've developed a an add-on with mobile support, this would apply to add-ons running on Android devices as well.

## Types of failures

Some failures will be more evident than others, but all will negatively impact the user experience of your add-on.

- If a nested iframe fails to load, Chrome displays a very obvious error message inside the iframe indicating that the domain "refused to connect".
- If an image fails to load, you may notice missing images in your add-on’s user interface. You should also see failures in the Network section of the browser’s developer tools.
- If a network call fails due to JavaScript code, you should see warning and error messages in the browser’s developer tools.

## Testing your add-on

Until Adobe Express enables these headers by default, you must configure your local development environment to simulate these changes.

### Apply local header overrides

The developer tools in Chromium-based browsers on the desktop allow you to specify header overrides. Using this, you can simulate the headers that Adobe Express will enable to test whether your add-on has any problems in this environment.

<InlineAlert slots="header, text" variant="info"/>

Mobile add-ons

You cannot test this on mobile devices. You should test your add-on on a desktop web browser powered by Chromium. Any issues you run into would also appear on mobile devices, and any fixes you apply would also apply to mobile users.

To enable this environment yourself, perform the following steps:

1. Open the developer tools:

 Launch your Chromium-based browser (e.g., Chrome, Edge, Opera).
 Open the developer tools by pressing `F12` or `Ctrl+Shift+I` (Windows/Linux) or `Cmd+Option+I` (Mac).

2. Navigate to the **Network** tab:

 In the developer tools, click on the **Network** tab, and then navigate to [Adobe Express](https://new.express.adobe.com) in the browser. Your network panel should fill up with a lot of network traffic, like this:

 ![Network panel screenshot](./img/coi-test-1.png)

3. Apply header overrides:

 To apply an override, right click on the entry for **new.express.adobe.com** and select **Override headers**.

 ![Override headers screenshot](./img/coi-test-2.png)

  **IMPORTANT:** Assuming you haven’t done this before, the developer tools will ask you to pick a folder on your local file system where these overrides are stored. The alert is easy to miss, since it doesn’t present as a dialog box, but rather a message near the top of your developer tool window.

  ![Override storage folder screenshot](./img/coi-test-3.png)

4. Select a local folder:

 Click **Select folder** to choose where you want to store the overrides. This will open your browser’s file picker. You’ll likely want to create a new folder for this step. You can put this anywhere you’d like. For example, in the following image we've selected the **Downloads** folder.

  ![Override downloads folder screenshot](./img/coi-test-4.png)

5. Allow access, if prompted:

 Depending on your operating system and the folder's location, the developer tools may need to request additional permissions to access it. If so, the message will again appear near the top of the developer tool window.

 ![Allow access screenshot](./img/coi-test-5.png)

 Click **Allow**. This may prompt an operating system level permissions prompt. In that case, be sure to allow that as well:

 ![OS permissions prompt screenshot](./img/coi-test-6.png)

6. Navigate to the **Sources** tab:

 Once any required permissions have been granted, navigate to the **Sources** tab in the developer tools:

 ![Sources panel screenshot](./img/coi-test-7.png)

7. Open the **Overrides** menu:

  Next, click the **`>>`** icon and select the **Overrides** menu option:

 ![>> Icon clicked screenshot](./img/coi-test-8.png)

 Expand the entry you see there completely. You should see something like the following:

 ![Overrides screenshot](./img/coi-test-9.png)

8. Add an override rule:

 To add an override rule, click the **Add override rule** option:

 ![Add override rules screenshot](./img/coi-test-10.png)

9. Enter the header names and values to override:

 Click on `header-name-1` and start entering the name of the first header -- in this case, `Cross-Origin-Embedder-Policy`.

 ![Header name screenshot](./img/coi-test-11.png)

 Press TAB or click into the field that says `header value` and update it to the appropriate value -– in this case, `credentialless`. Once done, click the **+** icon to add the next header.

 ![Credentialless header value](./img/coi-test-12.png)

10. Finalize header overrides:

 You’ll want to add headers until your overrides look like the following:

 ![Final header values screenshot](./img/coi-test-13.png)

11. Reload and test:

 At this point, you can reload Adobe Express and test your add-on. Be sure to watch the network panel for errors that your add-on might encounter.

### What to test in your add-on

You should test flows in your add-on that involve the following:

- **Purchase flows:** In particular, if you’re using an iframe to handle the purchase experience, you should also test an international purchase to ensure that any additional verification flows your payment provider requires also work. *Note: You're probably not impacted if you handle purchases in a new tab.*
- **Flows that load external domains in iframes:** For example, you may be using an iframe to generate a preview for the user or using an iframe to embed a video player.
- **Flows that display images and other content:** For example, if you’ve built an add-on that allows the user to add stickers and the stickers are served from your domain or another third party, you should verify that the images appear in the add-on’s user interface correctly. (If the content is bundled with your add-on, you should already be covered.)
- **Flows that add content to the user’s document:** Make sure that users can successfully add images or other assets to the document if your add-on provides this functionality. This should only apply to assets loaded from your domain or an external domain. Generated assets or assets bundled with your add-on should not have any issues.

If your add-on doesn’t access external content, make network calls, or use iframes to display content or payment flows, you should not be affected by this change.

## Disabling overrides

When you’re done testing, you’ll likely want to disable any header overrides in your browser’s developer tools. You can disable the overrides by unchecking **Enable Local Overrides** or by removing the header override directly.

![Disable overrides screenshot](./img/coi-test-14.png)

## Addressing issues found in your add-on

Applying fixes to your add-on is generally straightforward, but it depends on the issue you’re seeing.

### Fixing assets that fail to load

If the asset is in an `<img>` tag, you’ll want to set the `crossorigin` attribute. You can also set the `crossOrigin` property when using JavaScript. For examples, see the [MDN web documentation](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/crossOrigin).

### Fixing iframes or network calls that fail to load

You’ll need to set the following headers on the endpoint you’re trying to load. If loading an iframe, you’ll likely need to ensure these headers apply to all assets that can be loaded by the iframe.

- `Cross-Origin-Embedder-Policy: credentialless`
- `Cross-Origin-Resource-Policy: cross-origin`

If the endpoint is managed by a third party, you may have more difficulty in addressing the issue. Some things you can do:

- Check if the third party provider provides a mechanism to specify header overrides.
- Ask if the third party provider can set headers for you via their existing support channels.
- Create a proxy that you control to act as an intermediary. This has security and privacy implications since you need to ensure that the proxy is secure, doesn’t mix up or serve incorrect data, and doesn’t preserve user information for any longer than necessary to complete the transaction.

## [Review process impact](https://developer.adobe.com/express/add-ons/docs/guides/distribute/guidelines/general/)

All new add-ons published to the marketplace will be reviewed with these headers in place. If the reviewer finds a problem with your submission related to cross-origin isolation that impacts the usability of your add-on, the reviewer will reject your add-on. You can then use the above to address the issues before submitting again.
# Add-on iframe Context

Important details about the context of your add-on; permissions, security, CORS and more.

## iframe Sandbox

Your add-on is essentially a website running in a [sandboxed](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#sandbox) iframe. As a result, the content of your add-on runs in a low-privileged environment, has a subset of capabilities, and has an extra set of restrictions by default. It's important to understand how this may affect the add-on you're building, as well as how to learn to mitigate any problems you may run into along the way.

### Restrictions

The following set of restrictions are enabled when the `sandbox` attribute is applied to the `<iframe>` tag (ie: `<iframe sandbox=""`):

- The add-on bundle is served from a unique subdomain.
- Form submission is blocked.
- The Pointer Lock API (capturing mouse movement) is blocked.
- New windows or tabs cannot be opened from the add-on, unless overridden in the manifest.
- Add-ons can't use `<embed>`, `<object>`, `<applet>`, or similar.
- Add-ons cannot change the navigation of the top-level browsing context
Media can't be autoplayed.

### Permissions

The value of the `sandbox` attribute can either be empty (in which case all restrictions are applied), or a space-separated list of pre-defined permissions that remove a particular restriction. By default, **the `allow-scripts` and the `allow-same-origin` sandbox permissions are automatically set for all add-ons** (ie: `sandbox="allow-scripts allow-same-origin"`). The table below describes the rest of the permissions that can be applied to your add-on. These permissions can be applied by setting their values in the [manifest sandbox permissions](../../references/manifest/index.md#entrypointspermissionssandbox).

<!-- <InlineAlert slots="text" variant="info"/>

The add-on iframe automatically includes the `allow-scripts` and the `allow-same-origin` sandbox permissions by default (ie: `sandbox="allow-scripts allow-same-origin"`). The other supported permissions can be applied by setting their values in the [manifest sandbox permissions](../../references/manifest/index.md#entrypointspermissionssandbox). <br/><br/> -->

| Permission              | Description   |
| ------------------ | -----------:  |
| `allow-downloads`  |  Allow downloading files through an &lt;a&gt; or &lt;area&gt; element with the download attribute.         |
| `allow-popups`          | Allows the add-on to `window.open` popups |
| `allow-popups-to-escape-sandbox`   |  Allows a sandboxed document to open new windows without forcing the sandboxing flags upon them.         |
| `allow-presentation`  | Allows the add-on to start a presentation session.           |

<!-- The following two permissions are added to the `sandbox` attribute by default.

| Permission              | Description   |
| ------------------ | -----------:  |
| * `allow-same-origin`               | Removes the "different" origin policy           |
| * `allow-scripts` | Re-enables JavaScript.           | -->

**IMPORTANT:** Please note that these are currently the *only* permissions that are currently supported from [the set of sandbox permissions available](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe). Any other attributes are not supported or allowed in the manifest for your add-ons.

## CORS

In order to provide security to the users of your add-on, browsers implement a [CORS (Cross-Origin Resource Sharing)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) mechanism. This allows a service to control whether to allow JavaScript code to make requests from a different [origin](#origin). Many services decide to restrict access to specific [origins](#origin) (or [domains](#domain)), but many also allow developers to customize the [allowed list of origins](#allowed-list-of-origins) that can make requests to their service when creating an integration. When developing and testing your add-ons, it's important to understand where your add-on is being hosted, and what is being sent in the requests it's making specifically, to manage this security measure, and in the event you run into [CORS errors](../faq.md#why-do-i-receive-a-no-access-control-allow-origin-header-is-present-on-the-requested-resource-error).

<InlineAlert slots="text" variant="success"/>

Be sure to set your browser devtools option to "**Show CORS errors in console**". For example, in Chrome it looks like the screenshot shown below.

![Show CORS errors in Chrome screenshot](img/show-cors.png)

### Add-on subdomain

To help enable a smoother experience for developers dealing with CORS, we provide each add-on with a unique [subdomain](#subdomain) which can be supplied in the list of [allowed origins](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin) that can make requests to a given service.
Your add-on is given a unique ID when you go through the in-app distribution process for an add-on, to distribute it for private or public sharing. This ID will not change once it's been generated, regardless of [future distributions](../distribute/index.md), so we suggest that you create a private sharing link when you need it, even if you're still in the development phase. Your add-on's [subdomain](#subdomain) is assigned during this distribution process with a prefix of your unique add-on id, followed by the URL where it's hosted: `.wxp.adobe-addons.com`, for example: `src="https://w906hhl6k.wxp.adobe-addons.com/`.

#### Retrieving a subdomain

You can get a subdomain URL for your add-on during the development process by following the [add-on distribution steps](../distribute/private-dist.md) through [step 2](../distribute/private-dist.md#step-2-add-on-listing-settings), where your own unique subdomain URL is provided for your add-on. This step creates the container for your add-on and assigns a unique subdomain for where it will be hosted, so you can use it to set up CORS in advance. You can stop at the creation of the container if all you need is the subdomain at this point, and come back to create a listing on it later when you've finished your development. An example of what the settings panel with this URL looks like is shown below for reference. We provide a **Copy** button as well to allow you to easily copy your unique **Add-on URL**.

![add-on container settings panel](../distribute/img/settings-panel.png)

For existing add-ons, simply choose one in the distribution workflow and navigate to the new **Settings** tab and copy the **Add-on URL** field.

### Using the subdomain

There are multiple situations where you may run into a CORS issue and need to use the unique subdomain provided with your add-on to get past it. One way was described above, where you can just include it in the allowed list for a service integration. Another is to manage it by setting a server-side header, if you have access to that server. A third option is to use a [CORS proxy server](#cors-proxy-server). These options are described in the next sections below.

### Server-side CORS Handling

If you have access to the endpoint server your add-on is fetching from, you can set an [`Access-Control-Allow-Origin`](#allowed-list-of-origins) header with the value set to the subdomain of your add-on in the server's response object. Handling the headers on the server side is the ideal solution, but often times the issue occurs with services outside your control. In that case, your best bet is to use a CORS Proxy Server.

### CORS Proxy Server

Typically, the origin responsible for serving resources is also responsible for setting the access headers for those resources. However, in instances where you don't have access to the server, a proxy server can be set up to bypass the issue by acting as the intermediate server that makes the request for you, and returns the [`Access-Control-Allow-Origin`](#allowed-list-of-origins) header in the response with the the value of your subdomain.

#### Hosted CORS Proxy Server

One of the fastest ways to unblock your requests while testing in the event of CORS issues, is to use a hosted proxy server. For instance, `cors-anywhere` is a [NodeJS pakage](https://www.npmjs.com/package/cors-anywhere) which also has a free hosted demo server with it set up that you can use for quick testing. Open your browser to [https://cors-anywhere.herokuapp.com/](https://cors-anywhere.herokuapp.com/) and request temporary access to the demo server with the button shown in the screenshot:

![CORS diagram](img/cors-demo.png)

Then, simply prefix the URLs you're fetching with the `cors-anywhere` demo server URL of [https://cors-anywhere.herokuapp.com/](https://cors-anywhere.herokuapp.com/). For instance:

```js
let cors_anywhere = "https://cors-anywhere.herokuapp.com/";
let myUrl = "https://example.com/"; 
let url = cors_anywhere+myUrl;  

fetch(url).then(function (response) {        
    console.log(response);
})
```

  The response should be a successful response including that prefixed URL call:

`Response {type: 'cors', url: 'https://cors-anywhere.herokuapp.com/https://example.com/', redirected: false, status: 200, ok: true, …}`

<InlineAlert slots="text" variant="success"/>

Hosting your proxy server code in an online service like Cloudinary or Heroku is also a good option for handling CORS issues in your add-on development. These services provide a platform for deploying your code and can handle cross-origin requests for you. Additionally, using Cloudinary's [URL prefix feature](https://cloudinary.com/documentation/fetch_remote_images) can be a quick solution for handling CORS issues with remote images in your add-on development.

#### Locally Hosted CORS Proxy Server

You can also use the `cors-anywhere` node package to create and run your own proxy server locally for testing for instance, with a few easy steps. This can be useful if you want to modify the default settings or use different functions provided by the library. Follow the steps below to install and use it. Also be sure to run it on it's own port separate from where your add-on is running. Once you have it working as desired, you can modify the settings to host it externally to suit your needs.

1. Install the `cors-anywhere` node package:

    `npm install -g cors-anywhere` (or `npm i cors-anywhere` to install it in your current directory)

2. Create a file called `server.js` in your favorite editor and add the following to it:

    ```js
    // Listen on a specific host via the HOST environment variable
    var host = process.env.HOST || '0.0.0.0';
    // Listen on a specific port via the PORT environment variable
    var port = process.env.PORT || 8080;

    var cors_proxy = require('cors-anywhere');
    cors_proxy.createServer({
        originWhitelist: ['https://w906hhl6k.wxp.adobe-addons.com/'], // Your add-on subdomain
        requireHeader: ['origin', 'x-requested-with'],
        removeHeaders: ['cookie', 'cookie2']
    }).listen(port, host, function() {
        console.log('Running CORS Anywhere on ' + host + ':' + port);
    });
    ```

3. Run the server:
    `node server.js`

    or optionally pass in a host and port when you run it:
    `HOST=0.0.0.0 PORT=8080 node proxy-server.js`

#### CORS / COEP Handling

The value of the [**Cross-Origin-Embedder-Policy** (COEP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) header for add-on resources is set to `credentialless`, but you should be aware that it will be changing to use `require-corp` sometime in the future, so you should plan for that by ensuring resources loaded from within the document have CORP / CORS enabled. If you see any issues with fetch or using images, you can try implementing one of the following solutions.

1. For http requests, make sure that the resource server responds with the `Cross-Origin-Resource-Policy: cross-origin` header. See [this link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy) for reference.

2. If you're using the `<img>` tag and your resource is being served with CORS, add the `crossorigin` attribute to the HTML tag loading it, for example: `<img src="***" crossorigin>`. See [this link](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) for more details.

## Terms

### origin

A combination of a protocol (for example HTTP or HTTPS), hostname, and port (if specified). For example, in the URL `https://www.adobe.com:443/foo`, the "origin" is `https://www.adobe.com:443`.

### domain

A website's address on the Internet that is used in URLs to identify which server a specific webpage belongs to. A domain name consists of a sequence of names separated by periods and ending with an extension (ie: `wxp.adobe-addons.com`).

### subdomain

Subdomains are unique URLs that include an additional part to identify them in front of the main domain where it lives (ie: https://w906hhl6k.wxp.adobe-addons.com).

### allowed list of origins

A list of external domains that the server allows to request resources. This is typically enforced with a header defined on servers who enforce CORS, with the [`Access-Control-Allow-Origin`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin) header. This server-side header is returned to a [preflight request](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request), (dispatched transparently by the browser, before the request from your add-on itself), in order to determine if it's safe to send it when a cross-origin request is allowed.
# CORS Guide

## Overview

Express add-ons are run in a sandboxed iframe environment with a `null` origin, and this can cause issues when dealing with fetching from services that don't have CORS enabled or support a null origin.

When you suspect a CORS issue, check your browser console and you will likely see a message like the following in the browser console:

```Access to fetch at '<some-url>' from origin 'null' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.```

<InlineAlert slots="text" variant="success"/>

Be sure to have your browser devtools option set to "**Show CORS errors in console**". For example, in Chrome it looks like the screenshot shown below.

![Show CORS errors in Chrome screenshot](img/show-cors.png)

## Options

Some options for handling this error are described in the sections below.

### Server-side Handling

First, if you happen to have access to the endpoint server you are fetching from, you can add an `Access-Control-Allow-Origin` header with the value set to `*` in the server's response object. This wildcard setting in the header will allow access to the resources being requested by any site. However, note that this wildcard setting cannot be used with credentials. In the event that you need to use credentials, you can specify the origins that need support specifically, instead of the wildcard. Handling the headers on the server side is the ideal solution, but often times the issue occurs with services outside your control. In that case, your best bet is to use a CORS Proxy Server.

### CORS Proxy Server

Typically, the origin responsible for serving resources is also responsible for setting the access headers for those resources. However, in instances where you don't have access to the server, a proxy server can be set up to bypass the issue by acting as the intermediate server that makes the request for you, and returns the `Access-Control-Allow-Origin` header in the response with the required value needed to let the browser permit the access.

### Hosted CORS Proxy Server

One of the quickest ways to unblock your requests for testing, is to use a hosted proxy server which adds the CORS headers to the proxied request for you. For instance, `cors-anywhere` is a [NodeJS pakage](https://www.npmjs.com/package/cors-anywhere) which also has a free hosted demo server with it set up that you can use for quick testing. Open your browser to [https://cors-anywhere.herokuapp.com/](https://cors-anywhere.herokuapp.com/) and request temporary access to the demo server with the button shown in the screenshot:

![CORS diagram](img/cors-demo.png)

Then, simply prefix the URLs you're fetching with the `cors-anywhere` demo server URL of [https://cors-anywhere.herokuapp.com/](https://cors-anywhere.herokuapp.com/). For instance:

```js
let cors_anywhere = "https://cors-anywhere.herokuapp.com/";
let myUrl = "https://example.com/"; 
let url = cors_anywhere+myUrl;  

fetch(url).then(function (response) {        
    console.log(response);
})
```

  You should then receive a successful response with that prefixed URL call:

`Response {type: 'cors', url: 'https://cors-anywhere.herokuapp.com/https://example.com/', redirected: false, status: 200, ok: true, …}`

<InlineAlert slots="text" variant="success"/>

Hosting your proxy server code in an online service like Cloudinary or Heroku is also a good option for handling CORS issues in your add-on development. These services provide a platform for deploying your code and can handle cross-origin requests for you. Additionally, using Cloudinary's [URL prefix feature](https://cloudinary.com/documentation/fetch_remote_images) can be a quick solution for handling CORS issues with remote images in your add-on development.

### Locally Hosted CORS Proxy Server

You can also use the `cors-anywhere` node package to create and run your own proxy server locally for testing for instance, with a few easy steps. This can be useful if you want to modify the default settings or use different functions provided by the library. Follow the steps below to install and use it. Also be sure to run it on it's own port separate from where your add-on is running. Once you have it working as desired, you can modify the settings to host it externally to suit your needs.

1. Install the `cors-anywhere` node package:

    `npm install -g cors-anywhere` (or `npm i cors-anywhere` to install it in your current directory)

2. Create a file called `server.js` in your favorite editor and add the following to it:

    ```js
    // Listen on a specific host via the HOST environment variable
    var host = process.env.HOST || '0.0.0.0';
    // Listen on a specific port via the PORT environment variable
    var port = process.env.PORT || 8080;

    var cors_proxy = require('cors-anywhere');
    cors_proxy.createServer({
        originWhitelist: [], // Allow all origins
        requireHeader: ['origin', 'x-requested-with'],
        removeHeaders: ['cookie', 'cookie2']
    }).listen(port, host, function() {
        console.log('Running CORS Anywhere on ' + host + ':' + port);
    });
    ```

3. Run the server:
    `node server.js`

    or optionally pass in a host and port when you run it:
    `HOST=0.0.0.0 PORT=8080 node proxy-server.js`

<!-- <InlineAlert slots="text" variant="info"/> -->

#### HTTPS URL Support

By default, only `http` URLs are allowed with the sample code above (though the demo server supports either). To access `https` resources with your locally running script, you need to create and pass in a key and certificate in an `httpsOptions` object and include it as another object passed into the `createServer` call, such as:

```js
cors_anywhere = createServer({ 
    httpsOptions: { 
        key: fs.readFileSync(path.join(__dirname, 'key.pem')), 
        cert: fs.readFileSync(path.join(__dirname, 'cert.pem')), 
    }, 
}); 
```

## CORS / COEP Handling

The value of the **Cross-Origin-Embedder-Policy** (COEP) header for add-on resources is set to `require-corp`. With COEP set to `require-corp`, resources loaded from within the document need to have CORP / CORS enabled. If you see any issues with fetch or using images, you can try implementing one of the following solutions.

1. For http requests, make sure that the resource server responds with the `Cross-Origin-Resource-Policy: cross-origin` header. See [this link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy) for reference.

2. If you're using the `<img>` tag and your resource is being served with CORS, add the `crossorigin` attribute to the HTML tag loading it, for example: `<img src="***" crossorigin>`. See [this link](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) for more details.
# Using Web Frameworks and Libraries

## Typescript definitions

The Add-on SDK's are a set of interfaces written in TypeScript, and a TypeScript definitions package named `ccweb-add-on-sdk-types` is automatically included in the `package.json` for the `typescript` and `react-typescript` templates. As a result, a `add-on-ui-sdk.d.ts` file is generated in the `src` folder that exports the `AddOnUISdk` types, allowing you to take advantage of auto-completion and type checking capabilities. To use the type definitions, simply import them as needed in your `.ts` file, such as:

```ts
import {
  Application,
  AuthorizationRequest,
} from "@adobe-ccwebext/ccweb-add-on-sdk-types";
```

An example of how this works in Visual Studio Code is shown in this short clip below.<br/>

<div style="display: flex; justify-content: center;">
<iframe src="https://drive.google.com/file/d/1FzUaPZMjPD9k0ANQNibqRMiZRrSAIChg/preview" width="800" height="450" allow="autoplay"></iframe>
</div>

## Webpack & JavaScript bundler

When using Node libraries or other frameworks, you'll often need to use a JavaScript bundler. All of the templates the CLI provides (other than the basic `javascript` template) are pre-configured for webpack via the `--use` option set on the `ccweb-add-on-scripts` commands. If you create a new add-on project based on a react or typescript based template for instance, you will see the following `scripts` block generated in your `package.json`, and the existence of a `webpack.config.js` in the root of your project:

```json
"scripts": {
    "clean": "ccweb-add-on-scripts clean",
    "build": "ccweb-add-on-scripts build --use webpack",
    "start": "ccweb-add-on-scripts start --use webpack",
    "package": "ccweb-add-on-scripts package --use webpack"
},
```

However, if you want to use any other transpiler or bundler of your choice, you can do so, provided you have the correct configurations and packages installed (similar to how these templates have `webpack.config.js` defined, and its plugins and loaders installed). For example, if you want to use `tsc` to transpile the `.ts` files, you'll need to install the typescript package and add `tsconfig.json` to your project, then configure the script commands to make the transpilation and hosting work:

```json
"scripts": {
    "build": "ccweb-add-on-scripts build --use tsc",
    "start": "ccweb-add-on-scripts start --use tsc",
    "package": "ccweb-add-on-scripts package --use tsc"
}
```

<InlineAlert slots="text" variant="info"/>

The `src` folder in your project should contain all of your code and static asset files to ensure any changes you make are automatically detected by the hot module reloader, allowing you to see your updates immediately.

#### Update `webpack.config.js` with any new files to be copied

Configurations are included in the `webpack.config.js` generated with your add-on project for both development and production bundling (assuming your project was based on any template other than the basic javascript one). You should be aware that you will need to update the [`CopyWebpackPlugin`](https://www.npmjs.com/package/copy-webpack-plugin) block in your `webpack.config.js` to ensure any new files are copied into the `dist` folder at build time. For instance, if you add new image assets into your `src` folder that your add-on is using, you would need to ensure you include the file extension in the patterns of files getting copied, or you will get a 404 indicating the images are not found. If the images were type `.png` for instance, then you could include the additional `src/*.png` line like below to ensure they are copied:

```json
new CopyWebpackPlugin({
    patterns: [
        { from: "src/*.json", to: "[name][ext]" },
        { from: "src/*.png", to: "[name][ext]" }
    ]
})
```

## React

The CLI supports two different [react-based templates](../getting_started/dev_tooling.md#templates), and the [code samples](../../samples.md) repository contains various add-ons built with React for you to use as a reference.

## Lit Framework

The CLI provides [starter template options](../getting_started/dev_tooling.md#templates) which provide a basic setup to allow you to use the Lit framework, a lightweight library for building fast, lightweight web components. There are currently template options available for either using basic JavaScript (`swc-javascript`) with Lit or TypeScript (`swc-typescript`), preconfigured to help you get started.

<!-- To learn more about developing with [Lit](https://lit.dev/), be sure to check out the [Using Lit & TypeScript Guide](./using-lit-typescript.md). -->

## Other JavaScript and CSS libraries

You should be able to use any other JavaScript or CSS libraries you might want to include in your add-ons (ie: jQuery, Bootstrap) without any issues. Just make sure you include the necessary scripts and stylesheets in your project, and ensure they are bundled correctly by your chosen bundler.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Rendition
  - createRendition
  - exporting
  - output
title: Create Renditions
description: Create Renditions.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Create Renditions

Renditions are different output versions of a document made for specific purposes; for example, a high-quality PDF for printing or a smaller JPG for sharing online.

## Rendition settings

Renditions are created via the [`createRendition()`](../../../references/addonsdk/app-document.md#createrenditions) method of the `addOnUISdk.app.document` object. The method accepts two parameters:

1. [`renditionOptions`](../../../references/addonsdk/app-document.md#renditionoptions): controls the page range that is meant to be exported and the file format (jpg, png, mp4 and pdf).
2. [`renditionIntent`](../../../references/addonsdk/addonsdk-constants.md) constant (optional): controls the intent of the exported content (preview, export, print).

## Export content

Usually, you create renditions to allow users to download or share your content in different formats. This is a multi-step process that involves:

1. **Creating a new rendition** based on specific export configuration options via the [`createRendition()`](../../../references/addonsdk/app-document.md#createrenditions) method of the `addOnUISdk.app.document` object.
2. **Converting** the returned `blob` object into a URL via the `URL.createObjectURL()` method.
3. **Creating a download link** for the user to download the rendition, e.g., using the URL string from the previous step as the `href` attribute of an `<a>` element.

### Example

In the following snippet, we create a rendition of the current page in PNG format when the user clicks a button. We'll create a temporary anchor element to trigger the download of the rendition.

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  // Attach the rendition creation to a button click event
  document
    .querySelector("#download-button")
    .addEventListener("click", async () => {
      // Create a rendition of the current page
      const rendition = await addOnUISdk.app.document.createRenditions(
        // renditionOptions
        {
          range: addOnUISdk.constants.Range.currentPage,
          format: addOnUISdk.constants.RenditionFormat.png,
        },
        // renditionIntent
        addOnUISdk.constants.RenditionIntent.preview
      );

      console.log("Renditions created: ", rendition);
      // [{
      //   type: "page",
      //   blob: { size: 16195, type: "image/png" },
      //   title: "",
      //   metadata: { ... },
      // }];

      // Convert the blob into a URL to be consumed by an anchor element
      const downloadUrl = URL.createObjectURL(rendition[0].blob);

      // Create a temp/disposable anchor element to trigger the download
      const a = document.createElement("a");
      a.href = downloadUrl; // Set the URL
      a.download = "Preview_rendition.png"; // Set the desired file name
      document.body.appendChild(a); // Add the anchor to the DOM
      a.click(); // Trigger the download
      document.body.removeChild(a); // Clean up
      URL.revokeObjectURL(downloadUrl); // Release the object URL
    });
});
```

There are multiple classes that inherit from the `RenditionOptions` class, such as [`JpgRenditionOptions`](../../../references/addonsdk/app-document.md#jpgrenditionoptions), [`PngRenditionOptions`](../../../references/addonsdk/app-document.md#pngrenditionoptions), and [`PdfRenditionOptions`](../../../references/addonsdk/app-document.md#pdfrenditionoptions). Each of these classes has specific properties that can be set to control the output of the rendition.

```js
const JpgRendition = await addOnUISdk.app.document.createRenditions(
  // JpgRenditionOptions
  {
    range: addOnUISdk.constants.Range.currentPage,
    format: addOnUISdk.constants.RenditionFormat.jpg,
    // number in the range [0, 1]
    quality: 0.41,
    // no upscaling, result depends on the original image size/ratio
    requestedSize: { width: 600, height: 600 },
  }
);
```

```js
const pdfRendition = await addOnUISdk.app.document.createRenditions(
  // PdfRenditionOptions
  {
    range: addOnUISdk.constants.Range.currentPage,
    format: addOnUISdk.constants.RenditionFormat.pdn,
    bleed: { amount: 5, unit: addOnUISdk.constants.BleedUnit.mm },
  }
);
```

<InlineAlert slots="text" variant="info"/>

To allow the user to download the rendition, the **"permissions"** section should include `"allow-downloads"` in the `"sandbox"` array.

```json
{
  "testId": "cbe48204-578d-47cc-9ad4-a9aaa81dc3d3",
  "name": "Hello World", "version": "1.0.0", "manifestVersion": 2,
  "requirements": {
    "apps": [ { "name": "Express", "apiVersion": 1 } ],
  },
  "entryPoints": [
    {
      "type": "panel", "id": "panel1", "main": "index.html",
      "documentSandbox": "sandbox/code.js",
      "permissions": {
        "sandbox": [
          "allow-popups-to-escape-sandbox",
          "allow-popups",
          "allow-downloads" 👈 👀
        ]
      }
    }
  ]
}
```

Please also check out the [export-sample add-on](/samples.md#export-sample) for a more detailed example.

## The Preview intent

When the `renditionIntent` is set to `RenditionIntent.preview`, the output is created for **preview purposes only**. This means that the rendition is not meant to be downloaded or shared; for example, because the user is not on a paid Adobe Express plan and the design contains Premium content.

In this case, preview renditions are used either for processing purposes (e.g., if the add-on needs to perform data analysis on the design), or to be displayed in the add-on's panel or in a new window—making sure users cannot extract the content. Please see [this page](./premium_content.md#allow-only-the-preview-of-premium-content) for more detail on handling such scenarios.

<InlineAlert slots="text" variant="info"/>

When the `renditionIntent` is set to `RenditionIntent.preview`, you must add to the `manifest.json` a `"renditionPreview"` flag set to `true` in the **"requirements"** section.

```json
{
  "testId": "cbe48204-578d-47cc-9ad4-a9aaa81dc3d3",
  "name": "Hello World", "version": "1.0.0", "manifestVersion": 2,
  "requirements": {
    "apps": [ { "name": "Express", "apiVersion": 1 } ],
    "renditionPreview": true 👈 👀
  },
  "entryPoints": [
    // ...
  ]
}
```
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Metadata
  - Document
title: Document Metadata
description: Document Metadata.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Use Document Metadata

## Get the Document ID and Title

Through the [Add-on UI SDK Document object](../../../references/addonsdk/app-document.md), you can retrieve some information about the current document. Currently, there are asynchronous methods that allow you to retrieve the `id()` of the document and the `title()`. Also, associated events will let you listen for when the Document ID or the Document Title have changed, respectively via the `documentIdAvailable` and `documentTitleChange` events, which you can listen for with the [`addOnUISdk.app.on()`](../../../references/addonsdk/addonsdk-app.md#on) method.

### Example

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(() => {

  // Get the document ID
  const docId = await addOnUISdk.app.document.id();
  // urn:aaid:sc:VA6C2:679a7c92-33ce-4320-a610-f58ccaf56aa8

  // Get the document title
  const docTitle = await addOnUISdk.app.document.title();

  // Get the document Link
  const docLink = await addOnUISdk.app.document.link();
  
  console.log(`Document ID: ${docId}; Document Title: ${docTitle}`; `Document Link: ${docLink}`);  

  // Listen for document ID change
  addOnUISdk.app.on("documentIdAvailable", data => {
    console.log(`Document ID changed to: ${data.documentId}`);
  });

  // Listen for document title change
  addOnUISdk.app.on("documentTitleChange", data => {
    console.log(`Document title changed to: ${data.documentTitle}`);
  });
});
```

<InlineAlert slots="text" variant="warning"/>

Please remember that `id()`, `title()`, and `link()` are asynchronous methods and not properties of the `addOnUISdk.app.document` object. You need to call them and `await` for the promise to be resolved before using the returned value.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Drag and Drop
title: Use Drag-and-Drop
description: Use Drag-and-Drop.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Use Drag-and-Drop

## With local images

You must invoke the [`addOnUISdk.app.enableDragToDocument()`](/references/addonsdk/addonsdk-app.md#enabledragtodocument) method for each draggable image to implement this feature. It accepts two parameters: the `HTMLElement` and an object with a `previewCallback()` that returns the image URL for preview purposes, and a `completionCallback()` that fetches the corresponding blob to finalize insertion into the document.

You also need to listen for `"dragstart"` and `"dragend"` events to manage logs or other custom behaviour when the user interacts with the images.

### Example

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready before rendering elements in the DOM.
addOnUISdk.ready.then(async () => {
  // Create the image element in the DOM.
  const image = document.createElement("img");
  image.id = "image.jpg";
  // The image is local to the add-on.
  image.src = "./images/image.jpg";
  image.addEventListener("click", addToDocument);

  // Enable drag to document for the image.
  addOnUISdk.app.enableDragToDocument(image, {
    previewCallback: (element) => {
      // return the new URL for preview purposes
      return new URL(element.src);
    },
    completionCallback: async (element) => {
      // return the blob for the image
      return [{ blob: await getBlob(element.src) }];
    },
  });

  // Add the image to the document.
  document.body.appendChild(image);
});

// Utility functions

//Add image to the document.
async function addToDocument(event) {
  const url = event.currentTarget.src;
  const blob = await getBlob(url);
  addOnUISdk.app.document.addImage(blob);
}

// Handle "dragstart" event
function startDrag(eventData) {
  console.log("The drag event has started for", eventData.element.id);
}

// Handle "dragend" event
function endDrag(eventData) {
  if (!eventData.dropCancelled) {
    console.log("The drag event has ended for", eventData.element.id);
  } else {
    console.log("The drag event was cancelled for", eventData.element.id);
  }
}

// Get the binary object for the image.
async function getBlob(url) {
  return await fetch(url).then((response) => response.blob());
}
```

## With remote images or audio

To implement drag and drop with remotely hosted images, you similarly invoke `addOnUISdk.app.enableDragToDocument()`, but you fetch the resource from its remote URL. Provide a `previewCallback()` that returns the preview URL and a `completionCallback()` that retrieves the image as a blob. You can then attach the same `"dragstart"` and `"dragend"` event handlers to log or customize interactions as needed.

<InlineAlert slots="text" variant="warning"/>

To drag audio content, you must specify an additional `attributes` object with a `title` property. A note on how to include it is found in the following example.

### Example

```ts
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Enable drag support for an element
function makeDraggableUsingUrl(elementId: string, previewUrl: string) {
  const image = document.getElementById(elementId);

  const dragCallbacks = {
    previewCallback: (image: HTMLElement) => {
      // Return a new URL for the remote preview
      return new URL(previewUrl);
    },
    completionCallback: async (image: HTMLElement) => {
      // Fetch and return the image blob
      const imageBlob = await fetch(image.src).then((response) =>
        response.blob()
      );
      return [{ blob: imageBlob }];

      // ⚠️ for audio content, an attributes object
      // with the title is mandatory. For example:
      // return [{ blob: audioBlob, attributes: { title: "Jazzy beats" } }];
    },
  };

  try {
    addOnUISdk.app.enableDragToDocument(image, dragCallbacks);
  } catch (error) {
    console.log("Failed to enable DragToDocument:", error);
  }
}

// Log start of the drag event
addOnUISdk.app.on("dragstart", (eventData: DragStartEventData) => {
  console.log("The drag event has started for", eventData.element);
});

// Log end of the drag event
addOnUISdk.app.on("dragend", (eventData: DragEndEventData) => {
  if (!eventData.dropCancelled) {
    console.log("The drag event has ended for", eventData.element);
    disableDragToDocument();
  } else {
    console.log("The drag event was cancelled for", eventData.element);
    console.log("Cancel Reason:", eventData.dropCancelReason);
  }
});
```

## Notes

If the content being dragged is an animated GIF, it will be added as an animated GIF to the document, as long as it fits [the size criteria for animated GIF's](https://helpx.adobe.com/express/create-and-edit-videos/change-file-formats/import-gif-limits.html). In the event that it doesn't fit the size criteria, an error toast will be shown to the user.

Since the Add-on SDK uses pointer event handlers to perform drag operations, you should ensure that you don't attach any pointer event handlers that prevent default or stop propagation. Adding those types of handlers will kill the built-in handlers and cause the events not to work.

You should not attach `click` event listeners to drag-enabled elements in the capture phase, as the Add-on SDK attaches a `cancelClickEvent` handler to drag-enabled elements to ensure that the automatic click (pointer down + pointer up automatically fires a click event) doesn't fire. Adding other handlers to this same element will trigger them on drag & drop completion.

<InlineAlert slots="text" variant="info"/>

Use Chrome devTools to check the handlers attached to the element and its ancestors to identify any that may be causing conflicts with drag and drop handlers.

There are several [code samples](/samples.md) that implement drag and drop, including the [import-images-using-oauth](/samples.md#import-images-using-oauth) and [pix](/samples.md#pix) projects that you can reference.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Metadata
  - Element
title: Element Metadata
description: Element Metadata.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Element Metadata

## Get and Set Element Metadata

Add-ons can store **private metadata** (custom data accessible only to the add-on that set it) on any node within the Express document. Currently, each node can hold up to **3 KB** of data, organized as key/value pairs where both keys and values are Strings. Additionally, there is a limit of **20 key/value pairs** per node.

All nodes that inherit from the [`BaseNode`](../../../references/document-sandbox/document-apis/classes/BaseNode.md) class have a `addOnData` property that can be used to store and retrieve metadata. It is an instance of the [`AddOnData`](../../../references/document-sandbox/document-apis/classes/AddOnData.md) class, which provides methods to perform operations such as `getItem()`, `setItem()`, `removeItem()`, and `clear()`.

With the `remainingQuota` property, you can check how much space is left, both in terms of `sizeInBytes` and `numKeys`, while `keys()` returns an array of the keys in use.

<InlineAlert slots="text" variant="info"/>

While Document and Page metadata operate from the `addOnUISdk.app.document` object and belong to the [Add-on UI SDK](../../../references/addonsdk/index.md), Element metadata are part of the [Document Sandbox](../../../references/document-sandbox/document-apis/index.md) and are accessed through the `node.addOnData` property.

### Example

```js
import { editor } from "express-document-sdk";

// Create some dummy node
const text = editor.createText();
text.fullContent.text = "Hello, World!";

// Store some metadata as key/value pairs
text.addOnData.setItem("originalText", "Hello, World!");
text.addOnData.setItem("date", new Date().toISOString());

// Retrieve the metadata
console.log("Original text: ", text.addOnData.getItem("originalText"));

// Check the remaining quota
console.log("Remaining quota: ", text.addOnData.remainingQuota);
// {
//   "sizeInBytes": 3062,
//   "numKeys": 19
// }

// Check the keys in use
console.log("Keys in use: ", text.addOnData.keys());
// ["originalText", "date"]

// Remove the metadata
text.addOnData.removeItem("originalText");

// clear all metadata
text.addOnData.clear();
```

Please note that the `addOnData` property is iterable with `for...of` loops, so you can use it to iterate over the key/value pairs; each pair is an array with the key as the first element and the value as the second.

```js
// iterate over key/value pairs
for (let pair of text.addOnData) {
  console.log(pair);
  // ['originalText', 'Hello, World!']
  // ['date', '2025-01-20T11:06:19.051Z']
}
```

Alternatively, you can use the `keys()` method to get an array of all keys and then iterate over them.

```js
// Iterate over all keys
text.addOnData.keys().forEach((key) => {
  console.log(`Key: ${key}, Value: ${text.addOnData.getItem(key)}`);
});
```

## Use Cases

Per-element metadata can be useful to keep track, for example, of the original properties a node has been created with, the history of the subsequent changes made to it, or to tag some nodes in a way that is meaningful for the add-on (e.g., it's supposed to be skipped when a certain routine is launched). It can also be used to store temporary data that is not meant to be persisted.

Please, refer to the SDK Reference section for [`AddOnData`](../../../references/document-sandbox/document-apis/classes/AddOnData.md) for a complete list of methods, and the [`per-element-metadata`](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/per-element-metadata) sample add-on for a demonstrative implementation.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Group
  - Lock
  - Nest
title: Group Elements
description: Group Elements.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Group Elements

## Create a group

Groups are just like any other element in Adobe Express, very much like Text or Shapes: you must create them, and append them to the page. Interestingly, as instances of the [`GroupNode`](../../../references/document-sandbox/document-apis/classes/GroupNode.md) class, they can host other nodes in their `children` property.

To create a Group, you can use the [`editor.createGroup()`](../../../references/document-sandbox/document-apis/classes/Editor.md#creategroup) method.

### Example

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

// Create some Text
const greeting = editor.createText();
greeting.fullContent.text = "Hiya!";
greeting.translation = { x: 100, y: 50 };

// Create some other Text
const saluto = editor.createText();
saluto.fullContent.text = "Ciao!";
saluto.translation = { x: 100, y: 150 };

// Create a Group 👈
const greetingsGroup = editor.createGroup();
greetingsGroup.translation = { x: 100, y: 100 };

// Append the Text nodes to the Group 👈
greetingsGroup.children.append(greeting, saluto);

// Append the Group to the page 👈
editor.context.insertionParent.children.append(greetingsGroup);
```

<InlineAlert variant="info" slots="header, text, text1" />

Group append order

You can append the Group to the page and then append the Text nodes to the Group, or the other way around. The order doesn't matter, as long as the Group hits the page at some point.

Please note that the Text nodes in the example above haven't been appended to the page before getting into the group—they're invisible, until they're part of the Group and the Group itself ends on the page.

## Nest groups

Groups can be nested, meaning that you can have a Group inside another Group; just create the needed Group nodes and `append()` elements to their `children` property.

### Example

```js
// sandbox/code.js

// Create three different Text nodes
const greeting = editor.createText();
greeting.fullContent.text = "Hiya!";

const saluto = editor.createText();
saluto.fullContent.text = "Ciao!";

const salutation = editor.createText();
salutation.fullContent.text = "Salut!";

// Create an inner Group with the first two Text nodes
const innerGroup = editor.createGroup();
innerGroup.children.append(greeting, saluto);

// Create an outer Group with the inner Group and the third Text node
const outerGroup = editor.createGroup();
outerGroup.children.append(innerGroup, salutation);

editor.context.insertionParent.children.append(outerGroup);
```

This code results in the following grouping:

```txt
Outer Group
├── Inner Group
│   ├── Text Node: "Hiya!"
│   └─ Text Node: "Ciao!"
│
└── Text Node: "Salut!"
```

<InlineAlert variant="warning" slots="text" />

In Adobe Express, **Groups must contain at least two elements** to be valid—either other Groups or nodes. It's not possible to nest a single element within a Group, like for example, in Adobe Photoshop with Layers and Layer Sets.

## Element order

As you would intuitively expect, the order in which you append elements to a Group matters. The last element you append will be on top of the others, and the first one will be at the bottom.

As follows, a simple Square factory function creates and append a shape to the page, passing an option object with the `size` and `color` (grayscale) and `offset` properties. We'll be using it to test element order in a Group.

```js
// sandbox/code.js
function squareFactory({ size, color, offset = 0 }) {
  const rectangle = editor.createRectangle();

  // Define rectangle dimensions.
  rectangle.width = size;
  rectangle.height = size;

  const insertionParent = editor.context.currentPage;
  console.log(insertionParent.width, insertionParent.height);
  rectangle.setPositionInParent(
    {
      x: insertionParent.width / 2 + offset,
      y: insertionParent.height / 2 + offset,
    },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
  );
  // Define rectangle color.
  rectangle.fill = editor.makeColorFill(
    colorUtils.fromRGB(color, color, color, 1)
  );
  return rectangle;
}
```

### Example: last element on top

Creating a Group with two squares; the lighter one is added last, and it will be on top of the darker one.

```js
// sandbox/code.js
const s1 = squareFactory({ size: 50, color: 0.5 });
const s2 = squareFactory({ size: 50, color: 0.7, offset: 10 });
const group = editor.createGroup();
group.children.append(s1, s2);

editor.context.insertionParent.children.append(group);
```

![Grouping elements](./images/groups_above.png)

### Example: re-ordering elements

It's possible to re-order the elements in the Group by using the `children` property and the `moveAfter()` or `moveBefore()` method.

```js
// sandbox/code.js
const s1 = squareFactory({ size: 50, color: 0.5 });
const s2 = squareFactory({ size: 50, color: 0.7, offset: 10 });
const group = editor.createGroup();
group.children.append(s1, s2);
// s2 is on top of s1, as it's been added last

// Moves s1 after (on top of) s2
group.children.moveAfter(s1, s2);
editor.context.insertionParent.children.append(group);
```

![Grouping elements](./images/groups_below.png)

### Example: addding elements in a specific order

Similarly, it's possible to determine the elements insertion order with `insertAfter()` and `insertBefore()`.

```js
// sandbox/code.js
const s1 = squareFactory({ size: 50, color: 0.5 });
const s2 = squareFactory({ size: 50, color: 0.7, offset: 10 });
const s3 = squareFactory({ size: 50, color: 0.9, offset: 20 });
const group = editor.createGroup();
group.children.append(s1, s2);
// s2 is on top of s1, as it's been added last

// Inserts s3 after s1 (in the middle)
group.children.insertAfter(s3, s1);
editor.context.insertionParent.children.append(group);
```

![Grouping elements](./images/groups_middle.png)

## Move elements out of a Group

To move an element out of one Group (the source) and into another (the target), you can use the `children.append()` method of the target, passing the source element you want to move. It's no different from appending a new element to a Group, you just need to reference the source element regardless of where it is.

### Example

```js
// sandbox/code.js
const s1 = squareFactory({ size: 50, color: 0.1 });
const s2 = squareFactory({ size: 50, color: 0.3, offset: 10 });
const s3 = squareFactory({ size: 50, color: 0.5, offset: 20 });
const s4 = squareFactory({ size: 50, color: 0.7, offset: 30 });
const s5 = squareFactory({ size: 50, color: 0.9, offset: 40 });
const group1 = editor.createGroup();
const group2 = editor.createGroup();

// Grouping elements in two different groups
group1.children.append(s1, s2, s3);
group2.children.append(s4, s5);

editor.context.insertionParent.children.append(group1);
editor.context.insertionParent.children.append(group2);

// Moves s1 into group2
group2.children.append(s1);
// 👆 target group     👆 source element
```

## Remove elements

To remove an element from a Group, you can use the `remove()` method on the `children` property, which effectively also deletes the element from the document.

### Example

```js
// sandbox/code.js
const s1 = squareFactory({ size: 50, color: 0.5 });
const s2 = squareFactory({ size: 50, color: 0.7, offset: 10 });
const s3 = squareFactory({ size: 50, color: 0.9, offset: 20 });
const group = editor.createGroup();
group.children.append(s1, s2, s3);
editor.context.insertionParent.children.append(group);

// Removes s2 from the Group and from the page!
group.children.remove(s2);
```
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Storage
  - clientStorage
title: Store Data
description: Store Data.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Store Data

## Use the clientStorage API

Instead of relying solely on server-side data, you can use the **asynchronous** `clientStorage` API to store and retrieve data locally on the client-side. This can be useful for caching images, saving user preferences, or other scenarios where you want to avoid making repeated server requests.

Each add-on can store up to **10MB of data as key-value pairs**; supported values are not limited to strings, but also include objects, arrays, numbers, booleans, `null`, `undefined` and `Uint8Array`.

### Example

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

let store;

addOnUISdk.ready.then(async () => {
    store = addOnUISdk.instance.clientStorage;
}
/**
 * Store item
 */
async function setItem(item: string, isComplete: boolean) {
    await store.setItem(item, isComplete);
    todoItemInput.value = "";
}
/**
 * Log all storage item values
 */
async function displayAllItems() {
    const todoItems = await store.keys();
    todoItems.forEach(async (item: string) => {
        const itemValue = await store.getItem(item);
        console.log("Key: " + item + " value: " + itemValue);
    });
}
```

## Use Cases

Local data storage can be useful in many scenarios, such as when you need to cache data from server requests, store user UI preferences, pre-populate fields on load, or save temporary data. The fact that `clientStorage` support multiple data types makes it a more versatile tool to use compared to the Browser's `localStorage`.

Please, refer to the [SDK Reference section for clientStorage](/references/addonsdk/instance-clientStorage/) for a complete list of methods, and the [use-client-storage sample add-on](/samples.md#use-client-storage) for more details.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Dialogs
  - Modal dialogs
  - showModalDialog
title: Use Modal Dialogs
description: Use Modal Dialogs.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Use Modal Dialogs

When you need to pop up a dialog to show a certain message, such as an informational, warning, or error message, you can use a modal dialog.

Below are some examples of the different types. Also, check out the SDK references for details on how to [show](/references/addonsdk/addonsdk-app.md#showmodaldialog) or [programmatically close a dialog](/references/addonsdk/runtime-dialog.md#close), as well as the [dialog add-on sample](/samples.md#dialog-add-on) for more details.

## Simple Modal Dialog

You can show a dialog with the [`addOnUISdk.app.showModalDialog()`](../../../references/addonsdk/addonsdk-app.md#showmodaldialog) method, which accepts an options object containing the `variant`, `title`, `description` and, optionally, `buttonLabels`. The returned result object from a dialog will contain the `buttonType` clicked.

### Example

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(() => {
  // Utility function to show a confirmation dialog
  async function showConfirmDialog() {
    try {
      // Dialog Settings
      const dialogOptions = {
        // Available variants:
        // confirmation, information, warning,
        // destructive, error, input, custom
        variant: "confirmation",
        title: "Enable smart Filters",
        description: "Smart filters are editable filters.",
        // Available button labels: primary, secondary, cancel
        buttonLabels: { primary: "Enable", cancel: "Cancel" },
      };

      // Show the dialog
      const result = await addOnUISdk.app.showModalDialog(dialogOptions);

      // Log the button type clicked, return either "primary" or "cancel"
      console.log("Button type clicked " + result.buttonType);
    } catch (error) {
      console.log("Error showing modal dialog:", error);
    }
  }
  // Call the function to show the dialog
  showConfirmDialog();
});
```

### Input Modal Dialog

A dialog of variant `input` allows you to accept input from the user. The construction of the dialog is similar to the previous example, but with an additional [`field`](../../../references/addonsdk/addonsdk-app.md#field) object that defines the input field and has a `label`, `placeholder` and `fieldType` properties. In addition to the `buttonType`, the `fieldValue` is returned in the result object of the [`addOnUISdk.app.showModalDialog()`](../../../references/addonsdk/addonsdk-app.md#showmodaldialog) method.

### Example

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(() => {
  // Utility function to show an input dialog
  async function showInputDialog() {
    try {
      // Dialog Settings
      const inputDialogOptions = {
        variant: "input", // 👈
        title: "Please enter your key",
        description: "Your API key",
        buttonLabels: { cancel: "Cancel" },
        field: {
          // 👈
          label: "API Key",
          placeholder: "Enter API key",
          fieldType: "text",
        },
      };

      // Show the dialog
      const inputDialogResult = await addOnUISdk.app.showModalDialog(
        inputDialogOptions
      );

      if (inputDialogResultwi.buttonType === "primary") {
        // returns the input the user entered if they didn't cancel
        console.log("Field value", inputDialogResult.fieldValue); // 👈
      }
    } catch (error) {
      console.log("Error showing modal dialog:", error);
    }
  }
  // Call the function to show the dialog
  showInputDialog();
});
```

## Custom Dialog

If you need to show a dialog with custom content, you can use the `custom` variant. This allows you to define the content in a separate source file (e.g., a `dialog.html`) and specify the container's size and title.

### Example

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(() => {
  // Utility function to show a custom dialog
  async function showCustomDialog() {
    try {
      // Dialog Settings
      const customDialogOptions = {
        variant: "custom",
        title: "Custom Modal",
        src: "dialog.html", // use content from this html file
        size: { width: 600, height: 400 },
      };

      // Show the dialog
      const customDialogResult = await addOnUISdk.app.showModalDialog(
        customDialogOptions
      );

      // Log the result object
      console.log("Custom dialog result " + customDialogResult.result);
    } catch (error) {
      console.log("Error showing modal dialog:", error);
    }
  }
  // Call the function to show the dialog
  showCustomDialog();
});
```

Inside the custom dialog's HTML file, you can use the [`addOnUISdk.instance.runtime.dialog`](../../../references/addonsdk/runtime-dialog.md) object, especially its `close()` method, to programmatically close the dialog and set an optional return value.

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;

closeButton.onsubmit = () => {
  // User canceled the operation, close the dialog with no result
  addOnUISdk.instance.runtime.dialog.close();
};

createButton.onsubmit = () => {
  // return an object, to be captured in the result object
  addOnUISdk.instance.runtime.dialog.close({
    selectedDesign: "grid-layout",
  });
};
```

## Use Cases

Modals are versatile tools suitable for a wide range of scenarios. They can display simple information or warning pop-ups when you need users to confirm an action or provide input. Additionally, modals can present more complex content, such as custom dialogs that initiate the payment process for accessing add-on's premium features.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
  - Oauth
  - Authentication
  - Authorization
title: Use OAuth 2.0
description: Understand how to implement OAuth 2.0 authentication and authorization flows, including login, logout, and setup examples.
contributors:
  - https://github.com/hollyschinsky
  - https://github.com/undavide
---

# Use OAuth 2.0

Implementing an OAuth 2.0 authorization flow, enabling users to authenticate and log in using their existing accounts from third-party services.

A typical use case would be to use assets stored in different services. Here, you will find instructions on how to set it up and an implementation example. Check also the [SDK Reference OAuth section](https://developer.adobe.com/express/add-ons/docs/references/addonsdk/app-oauth/) for more options and details and the [import-images-using-oauth](/samples/#import-images-using-oauth) sample add-on for more advanced usage.

### Login and Logout flows

Both login and logout flows are equally important, and developers should ensure that the add-on's UI provides functionality for both actions.

Authorization should persist across sessions so users don't have to log in with their credentials every time they use the add-on. The token's lifespan is at the discretion of the OAuth provider; the token itself can be stored remotely (e.g., mapping its UUID in the add-on's local storage) or directly in the local storage (easier but less secure).

### Setup

The OAuth APIs can be used to obtain the authorization "code" from any OAuth 2.0 provider supporting the Code Exchange authorization workflow. You will need to go through some setup steps with the provider you want to use OAuth with first. Here are the steps to get started:

1. Log in to the OAuth provider's website and create an application (for example, Dropbox). This must be a web application, and if an option of SPA (Single Page Application) is listed, select it.
2. As an input to the "Redirect URIs" field, add: https://new.express.adobe.com/static/oauth-redirect.html.
3. Fill out other details as necessary and save the form. A client Id / application Id / application key (this differs on different OAuth providers) will be generated. Make note of it as you will need it in your add-on code.
4. Next, update your add-on `manifest.json` file with the hostname of the OAuth provider's authorization URL. **NOTE:** When using multiple providers, all hostnames must be provided. For example, if the add-on uses two OAuth providers (`"login.microsoftonline.com"` and `"www.dropbox.com"`), the `manifest.json` should contain both of them, as shown below:

```json
{
  "id": "<ADD_ON_ID>",
  "name": "<ADD_ON_NAME>",
  "version": "1.0.0",
  "manifestVersion": 1,
  "requirements": {
    "apps": ["Express"]
  },
  "entryPoints": [
    {
      "type": "panel",
      "id": "panel1",
      "label": {
        "default": "<ADD_ON_LABEL>"
      },
      "main": "index.html",
      "permissions": {
        "oauth": ["login.microsoftonline.com", "www.dropbox.com"]
      }
    }
  ]
}
```

### Example

Once you complete the setup, you can use the following code snippet as an example of how to perform the OAuth exchange to retrieve an access token. The [code samples](/samples.md) also include several examples of implementing OAuth 2.0 workflows, which you can refer to. Additionally, you'll find the [OAuthUtils.js](https://github.com/AdobeDocs/express-add-on-samples/blob/main/samples/import-images-using-oauth/src/utils/OAuthUtils.js) module, referenced below, and we recommend utilizing this module to facilitate your own OAuth implementation. For further details on the OAuth workflows, be sure to explore the [SDK References](https://developer.adobe.com/express/add-ons/docs/references/addonsdk/app-oauth).

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

const DROPBOX_AUTHORIZATION_URL = "https://www.dropbox.com/oauth2/authorize";
const DROPBOX_TOKEN_URL = "https://api.dropboxapi.com/oauth2/token";
const DROPBOX_CLIENT_ID = "<DROPBOX_CLIENT_ID>";
const DROPBOX_SCOPE = "<DROPBOX_SPACE_SEPARATED_SCOPES>";

const ONEDRIVE_AUTHORIZATION_URL = "https://login.microsoftonline.com/<AZURE_AD_TENANT_ID>/oauth2/v2.0/authorize";
const ONEDRIVE_TOKEN_URL = "https://login.microsoftonline.com/<AZURE_AD_TENANT_ID>/oauth2/v2.0/token";
const ONEDRIVE_CLIENT_ID = "<ONEDRIVE_CLIENT_ID>";
const ONEDRIVE_SCOPE = "<ONEDRIVE_SPACE_SEPARATED_SCOPES>";
const OWN_REDIRECT_URI = "<OWN_REDIRECT_URI>";

addOnUISdk.ready.then(() => {
  // 'oauthUtils' is a helper javascript module (included with
  // the OAuth sample) which provides utility functions to:

  // 1. Generate the 'code_challenge' and 'code_verifier' parameters
  // that are essential in the OAuth 2.0 workflow.
  // generateChallenge()

  // 2. Generate an 'access_token' and a 'refresh_token' using the
  // 'code' and 'redirectUri' received on successful authorization.
  // generateAccessToken()

  // Get an always valid 'access_token'.
  // 3. getAccessToken()
  const challenge = await oauthUtils.generateChallenge();
  await authorize(challenge);
});

function authorize(challenge) {
  // Trigger the OAuth 2.0 based authorization which opens up a
  // sign-in window for the user and returns an authorization code
  // which can be used to obtain an access_token.
  const { id, code, redirectUri, result } = await addOnUISdk.app.oauth.authorize({
    authorizationUrl: DROPBOX_AUTHORIZATION_URL,
    clientId: DROPBOX_CLIENT_ID,
    scope: DROPBOX_SCOPE,
    codeChallenge: challenge.codeChallenge
  });

  const { status, description } = result;
  if (status !== "SUCCESS") {
    throw new Error(`Status: ${status} | Description: ${description}`);
  }

  // Generate the access_token which can be used to verify the identity
  // of the user and grant them access to the requested resource.
  await oauthUtils.generateAccessToken({
    id,
    clientId: DROPBOX_CLIENT_ID,
    codeVerifier: challenge.codeVerifier,
    code,
    tokenUrl: DROPBOX_TOKEN_URL,
    redirectUri
  });

  const accessToken = await oauthUtils.getAccessToken(id);
}
```

## Use Cases

OAuth is ideal for scenarios where users need to connect their accounts to access personalized features, sync data, or enable functionalities like cloud storage. You can also use it to authenticate users and authorize them to access your add-on's premium users, after they've subscribed to a paid plan.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Metadata
  - Page
title: Page Metadata
description: Page Metadata.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Page Metadata

## Get the Page Metadata

If you want to retrieve metadata for pages in the document, use the [`getPagesMetadata()`](../../../references/addonsdk/app-document.md#getpagesmetadata) method in the `addOnUISdk.app.document` object. The method expects an object with a `range` and optional `pageIds` properties.

The `range` property is one of the available [`Range`](../../../references/addonsdk/addonsdk-constants.md) enumerables, either `currentPage`, `entireDocument`, or `specificPages`. If you choose `specificPages`, you must provide an array of page IDs in the `pageIds` property.

The returned value is always an array of [`PageMetadata`](../../../references/addonsdk/app-document.md#pagemetadata) objects.

### Single Page Example

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(() => {
  const page = await addOnUISdk.app.document.getPagesMetadata({
    range: addOnUISdk.constants.Range.currentPage
  });
  console.log("Current page metadata: ", page); // 👈 always returns an array
  // [
  //   {
  //     "id": "01d7093d-96d1-4d6a-981b-dc365343e17c",
  //     "size": { "width": 1080, "height": 1080 },
  //     "title": "First",
  //     "hasPremiumContent": false,
  //     "hasTemporalContent": false,
  //     "pixelsPerInch": 96
  //   },
  // ]
});
```

### Page Range Example

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(() => {
  const pages = await addOnUISdk.app.document.getPagesMetadata({
    range: addOnUISdk.constants.Range.specificPages,
    pageIds: [                                  // 👈
        "7477a5e7-02b2-4b8d-9bf9-f09ef6f8b9fc", // 👈
        "d45ba3fc-a3df-4a87-80a5-655e5f8f0f96"  // 👈
    ]                                           // 👈
  });
  console.log("Current page metadata: ", pages);
  // [
  //   {
  //     "id": "01d7093d-96d1-4d6a-981b-dc365343e17c",
  //     "size": { "width": 1080, "height": 1080 },
  //     "title": "First",
  //     "hasPremiumContent": false,
  //     "hasTemporalContent": false,
  //     "pixelsPerInch": 96
  //   },
  //   {
  //     "id": "8d5b1f9a-7289-4590-9ee4-a15a731698ed",
  //     "size": { "width": 1080, "height": 1080 },
  //     "title": "Second",
  //     "hasPremiumContent": false,
  //     "hasTemporalContent": false,
  //     "pixelsPerInch": 96
  //   }
  // ]
});
```

## Use Cases

Page metadata can be used to determine the size of the page, the title, and whether it contains temporal content (videos and animations). Tge `hasPremiumContent` property is particularly helpful when dealing with the rendition of [premium content](./premium_content.md)—for instance, when the user is not authorized to export/download assets that are available only to paid subscribers.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Position
  - Translation
  - Rotation
  - Bounding Box
  - Bounds
title: Position Elements
description: Position Elements.
contributors:
  - https://github.com/undavide
---

# Position Elements

## Move and Rotate Elements

Let's use this simple Rectangle to demonstrate how to move and rotate elements in Adobe Express.

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

const rect = editor.createRectangle();
rect.width = 200;
rect.height = 100;

editor.context.insertionParent.children.append(rect);
```

### Example: Translation

Elements can be moved around by setting their `translation` property, which is an object with `x` and `y` properties defined in the element's parent coordinates.

```js
// Move the rectangle 100px to the right and 50px down
rect.translation = { x: 50, y: 100 };
```

![Bounding Box](./images/position_bounding-box.png)

<InlineAlert slots="header, text1" variant="info" />

Mind the origin of the axes!

The zero point of the coordinate system is at the top-left corner of the parent container, with the x-axis pointing to the right and the y-axis pointing down. So, to move a shape to the right, you increase its `x` value; to move it down, you increase its `y` value.

A more advanced way to move shapes is by using the `setPositionInParent()` method, which takes two arguments: the **desired position** and the **reference point** of the shape.

```js
// Move the rectangle to the center of the artboard
const artboard = editor.context.currentPage.artboards.first;
rect.setPositionInParent(
  // Where to move the shape: the artboard center
  { x: artboard.width / 2, y: artboard.height / 2 },
  // Reference point of the shape
  { x: rect.width / 2, , y: rect.hwight / 2 } // the rectangle's center 👈
);
```

### Example: Rotation

You cannot rotate shapes by setting their `rotation` property, though; it's read-only, like `rotationInScreen`, which takes into account any cumulative rotations from the node's parent container. To rotate a shape, you must use `setRotationInParent()` instead, passing the **desired angle** in degrees, and the **point to rotate around**, in the shape's local coordinates. The `{ x: 0, y: 0 }` point in the example below is the shape's top-left corner.

```js
// sitting on the top-left corner
rect.translation = { x: 50, y: 100 };
// rotate 15 degrees around the rectangle's top-left corner
rect.setRotationInParent(15, { x: 0, y: 0 });
```

![Bounding Box](./images/position_rotate.png)

<InlineAlert slots="text1" variant="info" />

Please note, rotation and translation are never additive, meaning that each time you set a new value, it replaces the previous one.

## Get Element Bounds

By definition, the bounds of an element (or its _bounding box_) are the smallest rectangle that contains the element. The bounds are represented by a [Rect](../../../references/document-sandbox/document-apis/interfaces/Rect.md) object, which has a `x`, `y`, `width`, and `height` properties. There are two types of bounds, though, depending on the coordinate space in which they are calculated:

- **Local bounds**: The bounding box of an element in its own coordinate space (which may be shifted or rotated relative to its parent).
- **Parent bounds**: The bounding box of an element in its parent's coordinate space.

### Example: Local and Parent's Bounds

Let's see how to get the bounds of a rotated rectangle in both local and parent coordinates; since the rectangle is rotated, the two bounding boxes will differ.

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

const rect = editor.createRectangle();
rect.width = 200;
rect.height = 100;

rect.translation = { x: 50, y: 100 };
rect.setRotationInParent(15, { x: 0, y: 0 });

console.log(rect.boundsLocal);
// {x: 0, y: 0, width: 200, height: 100} 👈
console.log("boundsInParent", rect.boundsInParent);
// {x: 24.2, y: 100, width: 219.0, height: 148.3} 👈
editor.context.insertionParent.children.append(rect);
```

![Rotated Bounding Box](./images/position_rotated-bounding-box.png)

<InlineAlert slots="text1" variant="info" />

In case you need it, there's a handy `centerPointLocal` property of the element that returns the center point of the `boundsLocal` box.

## Account for Parent Transformations

The one Rectangle on the canvas, as we've used here for demonstration purposes, is but a simplified example; when dealing with real-world scenarios, the element's parent container may have a different rotation or translation, which affects the element's position and global angle. The Document Sandbox API provides some handy features that help you account for the parent's transformations.

### Example: Converting between coordinate spaces

In the following example, we'll create and group two rectangles; the group itself will be rotated and translated. We'll then find out the position of the second rectangle in the artboard's axis.

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

const rect1 = editor.createRectangle();
rect1.width = 200;
rect1.height = 200;
rect1.fill = editor.makeColorFill(colorUtils.fromHex("#ED672F"));
rect1.translation = { x: 0, y: 0 };

const rect2 = editor.createRectangle();
rect2.width = 200;
rect2.height = 50;
rect2.fill = editor.makeColorFill(colorUtils.fromHex("#F8CE94"));
rect2.translation = { x: 150, y: 150 };

// Group the rectangles
const group = editor.createGroup();
group.children.append(rect1, rect2);

// Rotate the group
group.setRotationInParent(10, { x: 0, y: 0 });

// Translate the group
group.translation = { x: 50, y: 50 };

// Add the group to the artboard
editor.context.currentPage.artboards.first.children.append(group);
```

![](./images/position_parent.png)

Where does the second rectangle sit in the artboard's coordinate system? To find out, we can use the [`localPointInNode()`](../../../references/document-sandbox/document-apis/classes/FillableNode.md#localpointinnode) method, which converts a point from the local coordinate space of the element to the parent's coordinate space.

```js
//...
console.log(
  rect2.localPointInNode(
    rect2.centerPointLocal, // the point to convert (the rectangle's center)
    editor.context.currentPage.artboards.first // the node to convert to (the artboard)
  )
);
// {x: 265.8, y: 265.8}   👈
```

### Example: Global Rotation

Similarly, you can calculate the global rotation of an element with the `rotationInScreen` property.

```js
//...
console.log(rect2.rotationInScreen);
// 10  👈
```
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Premium
  - Content
  - isPremiumUser
  - startPremiumUpgradeIfFreeUser
title: Manage Premium Content
description: Manage Premium Content.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

import '/src/styles.css'

# Manage Premium Content

When exporting Adobe Express documents, you should ensure proper handling of Premium content.

Let's go through all the available options to manage the rendition of Premium content in case your add-on allows users to export or download it.

## Show a Premium Content error with the "Upgrade" option

One way to handle premium content is to display a warning message when the user is not entitled to export or download it, and include a button to allow them to upgrade. Please note that you can detect in advance if the user is entitled to Premium content (via [`isPremiumUser()`](../../../references/addonsdk/app-currentUser.md#isPremiumUser)), and whether the page contains Premium content (via [`hasPremiumContent`](/references/addonsdk/app-document.md#pagemetadata)) in the first place. A try/catch block intercepting the `"USER_NOT_ENTITLED_TO_PREMIUM_CONTENT"` string in the error message as the primary way to deal with it is no longer recommended.

### Example

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
const { app, constants } = addOnUISdk;
const { ButtonType, Range, RenditionFormat } = constants;

const showPremiumContentError = async () => {
  // Show a modal dialog with an error message
  const { buttonType } = await window.addOnUISdk.app.showModalDialog({
    variant: "error",
    title: "Export failed",
    description:
      "Sorry, we were not able to export your design. " +
      "Some assets are only included in the Premium plan." +
      "Try replacing with something else " +
      "or upgrading Adobe Express to a Premium plan.",
    buttonLabels: { secondary: "Upgrade" },
  });

  // The User is still not premium
  if (buttonType === ButtonType.cancel) return false;
  if (buttonType === ButtonType.secondary) {
    // Original flow (don't use anymore)
    // ❌ window.open(
    //     "https://www.adobe.com/go/express_addons_pricing",
    //     "_blank"
    //   );
    // 👇 Use startPremiumUpgradeIfFreeUser() instead
    const hasUpgradedToPremium = await app.startPremiumUpgradeIfFreeUser();
    return hasUpgradedToPremium;
  }
};

// Check if the page range is safe to export
const isRangeSafeToExport = async (range) => {
  const userIsPremium = await app.currentUser.isPremiumUser();
  const pages = await app.document.getPagesMetadata({ range });
  const containsPremiumContent = pages.some((page) => page.hasPremiumContent);
  return (containsPremiumContent && userIsPremium) || !containsPremiumContent;
};

const exportDocument = async () => {
  // 👇 Testing purposes only! 👇
  app.devFlags.simulateFreeUser = true; // 👈 Remove in production!

  let isSafeToExport = await isRangeSafeToExport(Range.entireDocument);
  if (!isSafeToExport) {
    const isNowPremiumUser = await showPremiumContentError();
    isSafeToExport = isNowPremiumUser;
  }

  if (isSafeToExport) {
    try {
      const renditions = await app.document.createRenditions({
        range: Range.entireDocument,
        format: RenditionFormat.png,
      });
      renditions.forEach((rendition) => {
        // do your thing w/ the renditions
      });
    } catch (err) {
      // did someone just add premium content in the split second
      // between our original check? did the user just downgrade?
      if (err.message?.includes("USER_NOT_ENTITLED_TO_PREMIUM_CONTENT")) {
        return await exportDocument(); // try again
      }
    }
  }
};

document.querySelector("#export").onclick = exportDocument;
```

Please note that [`startPremiumUpgradeIfFreeUser()`](../../../references/addonsdk/addonsdk-app.md#startpremiumupgradeiffreeuser) allows a more streamlined user experience for upgrading to premium content, compared to the older method of redirecting to the Adobe Express pricing page, which is now deprecated.

## Provide visual cues in the UI

Alternatively, you can provide visual cues directly in the add-on UI to show that users are not entitled to export/download premium content. This can be done in various ways, for instance, by disabling the export/download button, replacing it with an upgrade button, or appending a brief explanation, tooltip, or icon. This would inform users upfront that they are not entitled to export/download premium content, preventing them from facing the warning popup after attempting to do so.

## Allow only the preview of Premium Content

As mentioned in [Creating Renditions](./create_renditions.md), you can allow users to preview Premium content within the iframe by setting the `renditionIntent` to the constant [`RenditionIntent.preview`](../../../references/addonsdk/addonsdk-constants.md) as the second parameter of the [`addOnUISdk.app.document.createRendition()`](../../../references/addonsdk/app-document.md#createrenditions) method. Remember to also add the [`"renditionPreview"`](./create_renditions.md#the-preview-intent) permission to your add-on's `manifest.json` file.

<InlineAlert slots="header, text, text1, text2" variant="warning"/>

Prevent previews download

Your add-on must not allow these previewed images to be downloaded or persisted on a backend (for any longer than necessary to serve the result back to the user). To that end, be sure that users cannot:

- **right-click -> save as**: To prevent this, reject the `contextmenu` event.
- **drag the image off the panel**: To prevent this, you can reject the `dragstart` event.

**Note:** These behaviors are enabled by default if you use an `<img>` tag. If you apply the image using `background-image` CSS, these behaviors aren't added.

### Example

<CodeBlock slots="heading, code" repeat="2" languages="JavaScript, TypeScript" />

#### JavaScript

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;

// Display preview of all pages in the AddOn UI
async function displayPreview() {
  try {
    const renditionOptions = {
      range: addOnUISdk.constants.Range.entireDocument,
      format: addOnUISdk.constants.RenditionFormat.png,
      backgroundColor: 0x7faa77ff,
    };
    const renditions = await addOnUISdk.app.document.createRenditions(
      renditionOptions,
      addOnUISdk.constants.RenditionIntent.preview
    );
    renditions.forEach((rendition) => {
      const image = document.createElement("img");
      image.src = URL.createObjectURL(rendition.blob);
      document.body.appendChild(image);
    });
  } catch (error) {
    console.log("Failed to create renditions:", error);
  }
}
```

#### TypeScript

```ts
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;

// Display preview of all pages in the AddOn UI
async function displayPreview() {
  try {
    const renditionOptions: PngRenditionOptions = {
      range: addOnUISdk.constants.Range.entireDocument,
      format: addOnUISdk.constants.RenditionFormat.png,
      backgroundColor: 0x7faa77ff,
    };
    const renditions = await addOnUISdk.app.document.createRenditions(
      renditionOptions,
      addOnUISdk.constants.RenditionIntent.preview
    );
    renditions.forEach((rendition) => {
      const image = document.createElement("img");
      image.src = URL.createObjectURL(rendition.blob);
      document.body.appendChild(image);
    });
  } catch (error) {
    console.log("Failed to create renditions:", error);
  }
}
```
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Theme
  - Locale
title: Theme & Locale
description: Theme & Locale.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Theme & Locale

## Detecting Theme

It can be useful to know what theme is currently set in Adobe Express, for instance to load a specific set of CSS in your add-on to keep its UI in sync, also in case the user changes it.

<InlineAlert slots="text" variant="info"/>

Currently, Adobe Express supports a "light" theme only, although a "dark" theme is planned for future releases.

The current theme is available in the [`addOnUISdk.app.ui.theme`](../../../references/addonsdk/app-ui.md#theme) property. Changes can be detected by listening to the `themechange` event on the [`addOnUISdk.app`](../../../references/addonsdk/addonsdk-app.md) object. The event will provide the new theme in the `data.theme` property.

### Example

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  // Get the current theme
  console.log(addOnUISdk.app.ui.theme); // "light"

  // Listen to theme changes
  addOnUISdk.app.on("themechange", (data) => {
    // data theme will be either "light" or "dark"
    console.log("The theme is now", data.theme);
    // ...
    // Apply the new theme to your add-on UI
  });
});
```

## Detecting Locale, Supported Locales, and Format

It's possible to retrieve the user's current locale, the list of supported locales, and detect when the locale changes (e.g., to set the language in your add-on accordingly). You can do so with the [`addOnUISdk.app.ui` object](/references/addonsdk/app-ui.md#locale) in the add-on SDK. Similarly, you can get and detect a change in the Format used display dates, times, numbers, etc. A simple example is shown below.

### Example

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(() => {
  // Get the currently supported locales
  console.log(addOnUISdk.app.ui.locales); // ["bn-IN", "cy-GB", ...]

  // Get the current locale
  console.log(addOnUISdk.app.ui.locale); // "en-US"

  // Get the current format
  console.log(addOnUISdk.app.ui.format); // "en-US"

  // Listen to locale changes
  addOnUISdk.app.on("localechange", (data) => {
    console.log("The locale is now", data.locale); // "fr-FR"
    // ...
  });

  // Listen to format changes
  addOnUISdk.app.on("formatchange", (data) => {
    console.log("The format is now", data.format); // "fr-FR"
    // ...
  });
});
```
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Audio
  - addAudio
title: Use Audio
description: Use Audio.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Use Audio

## Import audio into the page

Similarly to Images and Video, you can add Audio to the page using the [`addAudio()`](../../../references/addonsdk/app-document.md#addaudio) method of the `addOnUISdk.app.document` object, which expects a `Blob` object as the first argument, and a [`MediaAttribute`](../../../references/addonsdk/app-document.md#mediaattributes) object with the audio's title (mandatory) and author (optional) as the second.

### Example

```js
// sandbox/code.js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  try {
    const audioUrl =
      "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a11/a11a1021133-3114.mp3";

    const audio = await fetch(audioUrl);
    const audioBlob = await audio.blob();

    await addOnUISdk.app.document.addAudio(
      audioBlob, // 👈 Blob object
      {
        title: "Apollo 11 - Lunar Landing",
        author: "NASA",
      }
    );
  } catch (e) {
    console.error("Failed to add the audio", e);
  }
});
```

Please note that you can use `fetch()` also to get videos that are local to the add-on; in this case, you can use paths relative to the add-on's root.

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  try {
    // 👇 Local audio
     const audioUrl =
      "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a11/a11a1021133-3114.mp3";
    const audio = await fetch(audioUrl);
    // ... same as before
```

<InlineAlert slots="header, text" variant="info"/>

Audio file requirements

Please refer to [this page](https://helpx.adobe.com/au/express/create-and-edit-videos/change-file-formats/video-quick-actions-requirements.html) to know more about the file formats support and size/length requirements for audio.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Color
  - Fill Color
  - Stroke Color
  - Text Color
  - HEX Color
  - RGB Color
  - Color Picker
title: Use Color
description: Use Color.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Use Color

## Create colors

Colors in Adobe Express are created as instances of the [`Color`](../../../references/document-sandbox/document-apis/interfaces/Color.md) class: objects with `red`, `green`, `blue`, and `alpha` (optional) values in the range from 0 to 1. The `alpha` value represents the opacity of the color, with 0 being fully transparent and 1 fully opaque.

The entrypoint for creating colors is the [`colorUtils`](../../../references/document-sandbox/document-apis/classes/ColorUtils.md) class, imported from the `"express-document-sdk"`, so we're talking about [Document APIs](../../../references/document-sandbox/document-apis/index.md) here. Especially the static [`fromRGB()`](../../../references/document-sandbox/document-apis/classes/ColorUtils.md#fromrgb) and [`fromHex()`](../../../references/document-sandbox/document-apis/classes/ColorUtils.md#fromhex) methods.

```js
// sandbox/code.js
import { editor, colorUtils } from "express-document-sdk";

// Alpha is optional, defaults to 1
const red = colorUtils.fromRGB(1, 0, 0);
const green = colorUtils.fromHex("#00FF00");

// With alpha
const feldgrau = colorUtils.fromRGB(0.28, 0.32, 0.39, 0.5); // 50% opacity
const heliotrope = colorUtils.fromHex("#C768F780"); // 50% opacity
```

In case you need it, you can also convert a color to a HEX string using the [`toHex()`](../../../references/document-sandbox/document-apis/classes/ColorUtils.md#tohex) method. Please note that the alpha value is always included in the output string.

```js
const red = colorUtils.fromRGB(1, 0, 0);
const redHex = colorUtils.toHex(red); // #FF0000FF
```

## Apply colors

You can directly set the `color` property of a Text node via [`applyCharacterStyles()`](../../../references/document-sandbox/document-apis/classes/TextContentModel.md#applycharacterstyles):

### Example: Text color

```js
// sandbox/code.js
import { editor, colorUtils } from "express-document-sdk";

// Assuming the user has selected a text frame
const textNode = editor.context.selection[0];

// Apply character styles to the first three letters
textNode.fullContent.applyCharacterStyles(
  { color: colorUtils.fromHex("#E1A141") }, // 👈
  { start: 0, length: 3 }
);
```

See the [Use Text](./use_text.md) page for more examples.

### Example: Fill and Stroke colors

Colors are not directly applied, instead, to shapes; more generally, they are used to create [`Fill`](../../../references/document-sandbox/document-apis/interfaces/Fill.md) and [`Stroke`](../../../references/document-sandbox/document-apis/interfaces/Stroke.md) objects with the [`editor.makeColorFill()`](../../../references/document-sandbox/document-apis/classes/Editor.md#makecolorfill) and [`editor.makeStroke()`](../../../references/document-sandbox/document-apis/classes/Editor.md#makestroke) methods, respectively, that you can then apply to [`Fillable`](../../../references/document-sandbox/document-apis/classes/FillableNode.md) and [`Strokable`](../../../references/document-sandbox/document-apis/classes/StrokableNode.md) nodes.

If you're confused, worry not! This is the wondrous word of object oriented programming. The following example should clarify things:

```js
// sandbox/code.js
import { editor, colorUtils } from "express-document-sdk";

// Create the shape
const ellipse = editor.createEllipse();
ellipse.width = 100;
ellipse.height = 50;
ellipse.translation = { x: 50, y: 50 };

// Generate the needed colors
const innerColor = colorUtils.fromHex("#A38AF0");
const outerColor = colorUtils.fromHex("#2ACfA9");

// Make the colorFill and the Stroke
const innerColorFill = editor.makeColorFill(innerColor);
const outerColorStroke = editor.makeStroke({
  color: outerColor,
  width: 20,
});

// 👇 Apply the fill and stroke
ellipse.fill = innerColorFill;
ellipse.stroke = outerColorStroke;

// Add the shape to the document
editor.context.insertionParent.children.append(ellipse);
```

While the `fill` property is more straightforward to create, the `color` is just one of the possible properties of a `stroke`, as you can read in the [SolidColorStroke](../../../references/document-sandbox/document-apis/interfaces/SolidColorStroke.md) interface reference.

Simplifying the example above:

```js
// ...
ellipse.fill = editor.makeColorFill(colorUtils.fromHex("#A38AF0"));
ellipse.stroke = editor.makeStroke({
  color: colorUtils.fromHex("#2ACfA9"),
  width: 20,
});
// ...
```

<InlineAlert slots="header, text" variant="info"/>

Naming conventions

Please note that Adobe Express uses the terms **make** and **create** to distinguish between plain objects and live document objects. You `makeColorFill()`, but `createEllipse()`.

## Use the Color Picker

Adobe Express includes a native Color Picker, with special features such as Recommended Swatches, Eyedropper, Themes, Library and Brand colors. The Color Picker is available also to add-ons, you can invoke it using the [`addOnUISdk.app.showColorPicker()`](../../../references/addonsdk/addonsdk-app.md#showcolorpicker) method.

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently **_experimental only_** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../references/manifest/index.md#requirements) section of the `manifest.json`.

#### Benefits

- It simplifies the process of selecting a color, bypassing the Browser's color picker.
- It's in sync with any swatches or Brand colors defined in Adobe Express.
- It will evolve with Adobe Express, providing a consistent color picking experience across different parts of the application.

The `showColorPicker()` method accepts a reference to an HTML element as its first argument, which will become the color picker's anchor element. The picker will be positioned relative to this element, based on the placement options available in the `ColorPickerPlacement` enum; additionally, the anchor will receive a custom `"colorpicker-color-change"` event when the color changes and a `"colorpicker-close"` event when it is closed.

The `showColorPicker()` method requires an HTML element as its anchor point. Here's how it works:

1. **Anchor Element**

- Pass an HTML element reference as the first argument.
- The color picker will position itself relative to this element.
- Use the `ColorPickerPlacement` enum to control positioning.

2. **Event Handling**

- The anchor element receives two custom events:
  - `"colorpicker-color-change"`: Fires when a new color is selected.
  - `"colorpicker-close"`: Fires when the picker is closed.

### Example: Show the Color Picker

<CodeBlock slots="heading, code" repeat="2" languages="js, html"/>

#### ui/index.js

```js
import addOnUISdk, {
  ColorPickerEvents,
  ColorPickerPlacement,
} from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  // Get the button element
  const colorPickerButton = document.getElementById("colorPicker");

  // Add a click event listener to the button to show the color picker
  colorPickerButton.addEventListener("click", () => {
    addOnUISdk.app.showColorPicker(colorPickerButton, {
      // The title of the color picker
      title: "Awesome Color Picker",
      // The placement of the color picker
      placement: ColorPickerPlacement.left,
      // Whether the eyedropper hides the color picker
      eyedropperHidesPicker: true,
      // The initial color of the color picker
      initialColor: 0x0000ff,
      // Whether the alpha channel is disabled
      disableAlphaChannel: false,
    });
  });

  // Add a listener for the colorpicker-color-change event
  colorPickerButton.addEventListener(ColorPickerEvents.colorChange, (event) => {
    // Get the color from the event
    console.log(event.detail.color);
    // e.g., "#F0EDD8FF" in HEX (RRGGBBAA) format
  });

  // Add a listener for the colorpicker-close event
  colorPickerButton.addEventListener(ColorPickerEvents.close, (event) => {
    console.log(event.type); // "colorpicker-close"
  });
});
```

#### index.html

```html
<button id="colorPicker">Show the Color Picker</button>
```

Please note that the color returned by the `colorpicker-color-change` event is always a string in HEX format—with or without an alpha value, e.g., `#F0EDD8FF` or `#F0EDD8` depending on the `disableAlphaChannel` option.

### Example: Hide the Color Picker

You can decide to hide picker UI e.g., after a certain amount of time.

```js
colorPickerButton.addEventListener("click", () => {
  addOnUISdk.app.showColorPicker(colorPickerButton, {
    /* ... */
  });
  setTimeout(() => {
    console.log("Hiding the Color Picker after 10 seconds");
    addOnUISdk.app.hideColorPicker();
  }, 10000);
});
```

### Example: Use the color

You can use any HTML element as the color picker's anchor element; in the example below, we're using a `<div>` element to display a color swatch.

<CodeBlock slots="heading, code" repeat="2" languages="html, js"/>

#### index.html

```html
<style>
  #color-display {
    width: 30px;
    height: 30px;
    border: 1px solid black;
    border-radius: 4px;
    background-color: white;
  }
</style>
<body>
  <div id="color-display"></div>
</body>
```

#### index.js

```js
addOnUISdk.ready.then(async () => {
  const colorDisplay = document.getElementById("color-display");

  colorDisplay.addEventListener("click", () => {
    addOnUISdk.app.showColorPicker(colorDisplay, {
      title: "Color Picker 1",
      placement: ColorPickerPlacement.left,
      eyedropperHidesPicker: true,
    });
  });

  colorDisplay.addEventListener(ColorPickerEvents.colorChange, (event) => {
    // Update the color swatch display in the UI
    colorDisplay.style.backgroundColor = event.detail.color;
  });
});
```

To use the picked color in the Document Sandbox, you can use the [`colorUtils.fromHex()`](../../../references/document-sandbox/document-apis/classes/ColorUtils.md#fromhex) method, which converts the HEX color string to a [`Color`](../../../references/document-sandbox/document-apis/interfaces/Color.md) object.

```js
// sandbox/code.js
const color = colorUtils.fromHex(event.detail.color); // 👈 A Color object

// Use the color in the Document Sandbox, for example:
let selection = editor.context.selection;
if (selection.length === 1 && selection[0].type === "Text") {
  const textContentModel = selection[0].fullContent;
  textContentModel.applyCharacterStyles({ color }); // 👈 Using the color
}
```
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Shapes
  - Geometry
  - Rectangle
  - Ellipse
  - Path
title: Use Geometry
description: Use Geometry.
contributors:
  - https://github.com/undavide
---

# Use Geometry

## Create Shapes

Adobe Express provides a set of geometric shapes that you can create and style programmatically. These shapes are instances of the [`RectangleNode`](../../../references/document-sandbox/document-apis/classes/RectangleNode.md) and [`EllipseNode`](../../../references/document-sandbox/document-apis/classes/EllipseNode.md) classes, and you can draw them using the [`editor.createRectangle()`](../../../references/document-sandbox/document-apis/classes/Editor.md#createrectangle) and [`editor.createEllipse()`](../../../references/document-sandbox/document-apis/classes/Editor.md#createellipse) methods, respectively.

### Example: Add a Rectangle

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

const rect = editor.createRectangle();

// Define rectangle dimensions.
rect.width = 100;
rect.height = 100;

// The current page, where the rectangle will be placed
const currentPage = editor.context.currentPage;

// Append the rectangle to the page.
currentPage.artboards.first.children.append(rect);
```

<InlineAlert slots="header, text, text1" variant="warning"/>

Create vs. Add to the page

Factory methods such as `createRectangle()` and `createEllipse()` don't automatically add the shape to the page; while is exists and you can manipulate its properties, it won't be visible until you append it to **a container** like an [Artboard](../../../references/document-sandbox/document-apis/classes/ArtboardNode.md), a [Group](./group_elements.md), or any other instance of a class that implements the [`ContainerNode`](../../../references/document-sandbox/document-apis/interfaces/ContainerNode.md) interface.

You usually reference the container using [`editor.context`](../../../references/document-sandbox/document-apis/classes/Context.md), which provides access to the current page, selection, and other useful properties.

Please note that you can append multiple shapes at once with the `append()` method:

```js
const s1 = editor.createRectangle();
const s2 = editor.createEllipse();
// ... set all properties ...

editor.context.currentPage.artboards.first.children.append(s1, s2); // 👈
```

### Example: Add an Ellipse

Ellipses don't have a `width` and `height` properties, but a [`rx`](../../../references/document-sandbox/document-apis/classes/EllipseNode.md#rx) and [`ry`](../../../references/document-sandbox/document-apis/classes/EllipseNode.md#ry) (radius x, radius y) instead.

<InlineAlert slots="text" variant="warning"/>

An ellipse with a radius of 200 on the x-axis and 100 on the y-axis will result in a shape with 400 wide (`rx` times two) and a 200 tall (`ry` times two)!

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

const ellipse = editor.createEllipse();
ellipse.rx = 200; // radius x 👈
ellipse.ry = 100; // radius y 👈

console.log(ellipse.boundsLocal);
// { x: 0, y: 0, width: 400, height: 200 } 👈 mind the actual bounds!

// The current page, where the rectangle will be placed
const currentPage = editor.context.currentPage;

// Append the rectangle to the page.
currentPage.artboards.first.children.append(rect);
```

### Example: Style Shapes

Shapes have `fill` and `stroke` properties that you can use to style them. The following example demonstrates how to create a rectangle with a fill and a stroke.

```js
// sandbox/code.js
import { editor, colorUtils, constants } from "express-document-sdk";

// Create the shape
const ellipse = editor.createEllipse();
ellipse.rx = 200;
ellipse.ry = 100;

// 👇 Apply the fill color
ellipse.fill = editor.makeColorFill(colorUtils.fromHex("#F3D988"));

// 👇 Create the stroke
const stroke = editor.makeStroke({
  color: colorUtils.fromHex("#E29E4E"),
  width: 20,
  position: constants.StrokePosition.inside,
  dashPattern: [50, 2],
});

// 👇 Apply the stroke
ellipse.stroke = stroke;

// Add the shape to the document
editor.context.insertionParent.children.append(ellipse);
```

![Ellipse with fill and stroke](./images/shapes_ellipse.jpg)

<InlineAlert slots="text" variant="info"/>

If you need a refresher on how to create and apply colors, check out [Using Colors](./use_color.md).

## Create Paths

Paths are a versatile tool to create complex shapes in Adobe Express. The [`editor.createPath()`](../../../references/document-sandbox/document-apis/classes/Editor.md#createpath) method returns an instance of the [`PathNode`](../../../references/document-sandbox/document-apis/classes/PathNode.md) class, and accepts one [SVG string](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths) as the input.

### Example: Single path

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

const p1 = editor.createPath(
  `M224,151L142,151C142,151 145.69,129.772 144,119C147.578,121.515 153.324,124.558 153,124C153.551,119.627 149,115 149,115C154.041,111.701 155.245,104.477 150,110C151.775,105.754 151.55,100.222 146,107C140.45,113.778 150.733,97.726 152,89C153.267,80.274 143.163,79.42 137,77C130.837,74.58 133.264,72.337 133,71C130.052,80.34 126.261,82.078 123,81C119.567,79.866 119.164,65.513 125,57C120.007,59.519 119,58 119,58C128.157,53.412 134.031,44.13 132,42C129.969,39.87 114.451,41.06 106,54C97.549,66.94 99.126,73.868 104,79C96.435,82.127 72,99 72,99C72,99 65.521,102.836 59,102C59.031,109.474 62.37,105.88 65,105C61.399,110.264 61.382,114.8 62,119C64.225,116.9 64,115 64,115C64,115 64.124,118.136 64,122C65.53,120.78 66,119 66,119C66,119 65.324,128.405 66.474,127.387C69.247,124.933 72.234,118.577 74,105C78.171,103.746 106,92 106,92C109.996,104.248 115.941,119.738 112,151L91,151`
);

editor.context.insertionParent.children.append(p1);
```

![Google "Osvaldo Cavandoli". You're welcome](./images/paths_linea.png)

### Example: Multiple paths

Combining and grouping multiple paths, you can create complex shapes, like in the following example:

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

const p1 = editor.createPath(
  `M310,222 A92,92 0 1,0 126,222 A92,92 0 1,0 310,222 Z`
);
const p2 = editor.createPath(
  `M425.096,209.235 
    C425.096,209.235 520.492,413.969 554.392,486.722 
    C556.956,492.226 556.533,498.659 553.270,503.779 
    C550.007,508.900 544.355,512.000 538.283,512.000 
    C453.556,512.000 199.784,512.000 115.057,512.000 
    C108.985,512.000 103.333,508.900 100.070,503.779 
    C96.807,498.659 96.384,492.226 98.948,486.722 
    C133.289,413.023 230.896,203.545 230.896,203.545 
    L278.678,236.000 L331.559,195.000 L383.266,236.000 L425.096,209.235 Z`
);
const p3 = editor.createPath(
  `M230.896,203.545 
    L278.041,102.365 
    C286.849,83.461 305.815,71.375 326.670,71.375 
    C347.525,71.375 366.491,83.461 375.299,102.365 
    L425.096,209.235 L383.266,236.000 L331.559,195.000 
    L278.678,236.000 L230.896,203.545 Z`
);
const p4 = editor.createPath(`M218,106 L218,66`);
const p5 = editor.createPath(`M160.074,121.590 L140.074,87.150`);
const p6 = editor.createPath(`M117.878,164.193 L83.138,144.193`);
const p7 = editor.createPath(`M101.831,222.119 L61.831,222.119`);
const p8 = editor.createPath(`M118.076,280.194 L83.336,300.194`);

const g = editor.createGroup();
g.children.append(p1, p2, p3, p4, p5, p6, p7, p8);

editor.context.insertionParent.children.append(g);
```

![Path](./images/paths_complex.png)

### Example: Add Fills and Strokes

`PathNode` instances have `fill` and `stroke` properties that you can use to style the path, very much like, say, a [`RectangleNode`](../../../references/document-sandbox/document-apis/classes/RectangleNode.md). In the code snippet below, we're going to add some life to the path from the previous example.

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

const p1 = editor.createPath(/* same as before... */);
const p2 = editor.createPath(/* same as before... */);
const p3 = editor.createPath(/* same as before... */);
const p4 = editor.createPath(/* same as before... */);
const p5 = editor.createPath(/* same as before... */);
const p6 = editor.createPath(/* same as before... */);
const p7 = editor.createPath(/* same as before... */);
const p8 = editor.createPath(/* same as before... */);

const g = editor.createGroup();
g.children.append(p1, p2, p3, p4, p5, p6, p7, p8);

// Create a black stroke to apply to all paths
const blackStroke = editor.makeStroke({
  color: colorUtils.fromRGB(0, 0, 0, 1),
  width: 10,
});

// Apply the stroke to all paths in the group
for (const path of g.children) {
  path.stroke = blackStroke;
}

// Apply different fills to the paths
p1.fill = editor.makeColorFill(colorUtils.fromHex("#f2af0d"));
p2.fill = editor.makeColorFill(colorUtils.fromHex("#33cc7b"));
p3.fill = editor.makeColorFill(colorUtils.fromHex("#ffffff"));

editor.context.insertionParent.children.append(g);
```

![Path](./images/paths_styled.png)
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Images
  - addImage
title: Use Images
description: Use Images.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Use Images

## Import Images into the page

Add-ons are hosted in an iframe within the Adobe Express UI, and can load images as `<img>` elements like any other web application. But in order to add images into an Adobe Express document, you need to use the [`addImage()`](../../../references/addonsdk/app-document.md#addimage) method of the `addOnUISdk.app.document` object.

It expects a `Blob` object as the first argument, and an optional [`MediaAttribute`](../../../references/addonsdk/app-document.md#mediaattributes) object with the image's title and author.

### Example

```js
// sandbox/code.js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  try {
    const imageUrl = "https://placehold.co/600x400.png";
    const image = await fetch(imageUrl);
    const imageBlob = await image.blob();

    await addOnUISdk.app.document.addImage(
      imageBlob, // 👈 Blob object
      {
        title: "Placeholder image", // 👈 Optional MediaAttributes
        author: "Adobe Developer",
      }
    );
  } catch (e) {
    console.error("Failed to add the image", e);
  }
});
```

Please note that you can use `fetch()` also to get images that are local to the add-on; in this case, you can use paths relative to the add-on's root.

```js
// sandbox/code.js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  try {
    const imageUrl = "./600x400.png";     // 👈 Local image
    const image = await fetch(imageUrl);
    // ... same as before
```

<InlineAlert slots="header, text" variant="info"/>

Image requirements

Please refer to [this section](../../../references/addonsdk/app-document.md#image-requirements) to know more about the file formats support and size requirements for images.

## Import Animated images

Importing a `GIF` via `addImage()` won't work as expected, as the method converts the animation into a static image before adding it to the document. You should use the [`addAnimatedImage()`](../../../references/addonsdk/app-document.md#addanimatedimage) method instead.

### Example

```js
// sandbox/code.js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  try {
    const gifImageUrl = "https://path/to/a/file.gif"; // 👈 a GIF image
    const gifImage = await fetch(gifImageUrl);
    const gifImageBlob = await gifImage.blob();

    await addOnUISdk.app.document.addAnimatedImage(
      // 👈
      gifImageBlob, // 👈 Blob object
      {
        /* ... */
      } // 👈 Optional MediaAttributes
    );
  } catch (e) {
    console.error("Failed to add the image", e);
  }
});
```

<InlineAlert slots="header, text" variant="warning"/>

GIF Image requirements

All image formats are equal, but some formats are more equal than others. Please refer to [this FAQ](../../faq.md#are-animated-gifs-supported-when-importing-or-dragging-content-to-the-document) to learn more about specific GIF limitations in terms of size and weight.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - PDF Import
  - PowerPoint Import
  - importPdf
  - importPowerPoint
title: Use PDF and PowerPoint
description: Use PDF and PowerPoint.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Use PDF and PowerPoint

## Import PDF into the page

You can add PDFs to the page using the [`importPdf()`](../../../references/addonsdk/app-document.md#importpdf) method of the `addOnUISdk.app.document` object, which expects a `Blob` object as an argument and a [`MediaAttribute`](../../../references/addonsdk/app-document.md#mediaattributes) object with a title (mandatory) and author (optional) as the second.

PDF and PowerPoint imports will trigger a consent dialogue that asks the user to confirm the process; it's not possible to bypass it. As soon as the process starts, another dialogue will preview the PDF and track the operation progress.

![PDF Import dialogue](./images/pdf_import.png)

Supported vector elements will be kept editable (e.g., shapes with rounded corners, text, etc.), and all pages will be imported.

### Example

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  try {
    const pdfUrl = "https://url/to/your/file.pdf";

    const pdf = await fetch(pdfUrl);
    const pdfBlob = await pdf.blob();

    await addOnUISdk.app.document.importPdf(
      pdfBlob, // 👈 Blob object
      {
        title: "Official Launch Party",
        author: "Adobe",
      }
    );
  } catch (e) {
    console.error("Failed to add the PDF", e);
  }
});
```

Please note that you can use `fetch()` also to get PDFs that are local to the add-on; in this case, you can use paths relative to the add-on's root.

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  try {
    // 👇 Local PDF
     const pdfUrl = "./OfficialLaunchParty.pdf";
    const pdf = await fetch(pdfUrl);
    // ... same as before
```

## Import PowerPoint into the page

For PowerPoint files, the process is similar to the one for PDFs, but you need to use the [`importPowerPoint()`](../../../references/addonsdk/app-document.md#importpresentation) method instead. The method supports both `.pptx` and `.ppt` files, and shows the same consent and progress dialogues as seen above.

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  try {
    const powerPointUrl = "https://url/to/your/file.pptx";
    // Or
    // const powerPointUrl = "./OfficialLaunchParty.pptx";

    const powerPoint = await fetch(powerPointUrl);
    const powerPointBlob = await powerPoint.blob();

    await addOnUISdk.app.document.importPowerPoint(
      powerPointBlob, // 👈 Blob object
      {
        title: "Official Launch Party",
        author: "Adobe",
      }
    );
  } catch (e) {
    console.error("Failed to add the PDF", e);
  }
});
```
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Text
  - Style Text
  - TextNode
  - Paragraph Styles
  - Character Styles
  - Fonts
  - Text Flow
  - Text Content
  - Text Styles
  - fullContent
  - applyCharacterStyles
  - applyParagraphStyles
  - fromPostscriptName
  - AvailableFont
title: Use Text
description: Use Text.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Use Text

Text is an essential part of any design. Let's explore how to use all the available APIs to create and style it.

## Create Text

The `editor.createText()` method doesn't accept any parameters and returns a brand new [`TextNode`](../../../references/document-sandbox/document-apis/classes/TextNode.md). The actual textual content starts as empty and is found in its [`fullContent.text`](../../../references/document-sandbox/document-apis/classes/TextContentModel.md#text) property.

### Example

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

// Create a new TextNode
const textNode = editor.createText();

// Set the text content
textNode.fullContent.text = "Hello,\nWorld!";

// Center the text on the page
const insertionParent = editor.context.insertionParent;
textNode.setPositionInParent(
  { x: insertionParent.width / 2, y: insertionParent.height / 2 },
  { x: 0, y: 0 }
);

// Add the TextNode to the document
insertionParent.children.append(textNode);

// Get the text content
console.log("Text: ", textNode.fullContent.text);
```

The text is created with the default styles (Source Sans 3, 100pt, black). Use `\n` or `\r` to add a line break.

## Replace Text

The text content of a `TextNode` can be replaced by setting the [`fullContent.text`](../../../references/document-sandbox/document-apis/classes/TextContentModel.md#text) property.

### Example

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

// Assuming the user has selected a text frame
const selectedTextNode = editor.context.selection[0];
selectedTextNode.fullContent.text = "Something else";
```

## Apply Character Styles

Text styles can be applied to a `TextNode` using the [`fullContent.applyCharacterStyles()`](../../../references/document-sandbox/document-apis/classes/TextContentModel.md#applycharacterstyles) method, which applies one or more styles to the characters in the given range, leaving any style properties that were not specified unchanged.

The styles are defined by the [`CharacterStylesInput`](../../../references/document-sandbox/document-apis/interfaces/CharacterStylesInput.md) interface; the properties that can be set are:

- color
- font (please see the [Use Fonts](#use-fonts) section)
- fontSize
- letterSpacing
- underline

The range is an object with the `start` and `length` properties.

<InlineAlert slots="header, text" variant="warning"/>

Style Ranges and Text edits

For the moment, replacing the `fullContent.text` will result in applying the style from the first range to the whole text. This behavior is subject to change in future releases.

Please note that `applyCharacterStyles()` is only one way to set styles; you can also use the `characterStyleRanges` property, which supports both getting and setting styles, as described [here](#example-set-all-styles).

### Example: Set Styles in a range

Let's change the styles for the first three characters of a TextNode.

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

// Assuming the user has selected a text frame
const textNode = editor.context.selection[0];

// Apply character styles to the first three letters
textNode.fullContent.applyCharacterStyles(
  {
    color: { red: 0, green: 0.4, blue: 0.8, alpha: 1 },
    fontSize: 240,
    letterSpacing: 10,
    underline: true,
  },
  {
    start: 0,
    length: 3,
  }
);
```

The `applyCharacterStyles()` method is not the only one that allows you to set styles; you can also use the `characterStyleRanges` property, which supports both getting and setting styles.

### Example: Get all Styles

To get the complete list of text character styles, you can use the [`fullContent.characterStyleRanges`](../../../references/document-sandbox/document-apis/classes/TextContentModel.md#characterstyleranges) property, which returns an array of [`CharacterStylesRange`](../../../references/document-sandbox/document-apis/interfaces/CharacterStylesRange.md) elements.

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

// Assuming the user has selected a text frame
const textNode = editor.context.selection[0];
const contentModel = textNode.fullContent;

// Get the array of character styles
const existingStyles = contentModel.characterStyleRanges;

// Edit some properties
existingStyles[0].fontSize = 10;

// Reassign the array to apply the style changes
contentModel.characterStyleRanges = existingStyles;
```

### Example: Set all Styles

You can also use the [`characterStyleRanges`](../../../references/document-sandbox/document-apis/classes/TextContentModel.md#characterstyleranges) property to set individual ranges or them all. It's always best to get the array, modify it, and then reassign it.

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

// Assuming the user has selected a text frame
const textNode = editor.context.selection[0];
const contentModel = textNode.fullContent;

// Get the array of character styles
const existingStyles = contentModel.characterStyleRanges;

// Edit some properties: the font size of all styles
existingStyles.forEach((style) => {
  style.fontSize = 50;
});
// Alternatively, you could set the properties for a specific style range
// existingStyles[0].fontSize = 50;

// Reassign the array to apply the style changes
contentModel.characterStyleRanges = existingStyles;
```

### Example: Reapply Styles

In the current release, automatic preservation of the Character Style configuration is not available when editing a TextNode’s content via the `fullContent.text`. As a temporary solution, you can save the existing character style ranges before updating the text and reapply them afterward to maintain your custom styles.

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

// Assuming the user has selected a text frame
const textNode = editor.context.selection[0];
const contentModel = textNode.fullContent;

// Save existing character style ranges
const savedStyles = contentModel.characterStyleRanges;

// Replace the text content
contentModel.text = "Updated text content\nwith preserved styles";

// Reapply the saved character styles
contentModel.characterStyleRanges = savedStyles;
```

<InlineAlert slots="text" variant="warning"/>

If the text content differs too much from the original, the character style ranges might not be reapplied correctly. This is a temporary solution until automatic preservation of character styles is available.

## Use Fonts

In the Adobe Express Document API, Fonts are part of the Character Styles; we're treating them separately here for clarity. Similarly to the color and other properties, you can use individual [`CharacterStylesRange`](../../../references/document-sandbox/document-apis/interfaces/CharacterStylesRange.md) items from the [`CharacterStyleRanges`](../../../references/document-sandbox/document-apis/classes/TextContentModel.md#characterstyleranges) array as Font getters and setters, or use the [`applyCharacterStyles()`](../../../references/document-sandbox/document-apis/classes/TextContentModel.md#applycharacterstyles) method to apply a Font style to a specific range.

The only caveat is that you cannot set the font as an Object literal, like, e.g., colors; fonts must be of type [`AvailableFont`](../../../references/document-sandbox/document-apis/classes/AvailableFont.md), and are instantiated from the `fonts` object (imported from the `"express-document-sdk"`) using the asynchronous `fromPostscriptName()` method.

```js
// Always
✅ const font = await fonts.fromPostscriptName("SourceSans3-Bold");

// Won't work
❌ const font = {
  availableForEditing: true,
  isPremium: false,
  family: "Source Sans 3",
  postscriptName: "SourceSans3-Bold",
  style: "Bold",
}
```

You can get PostScript names by setting different text fonts in the Adobe Express UI; then, log and inspec the `font` property of `characterStyleRange`, as seen [here](#example-get-all-styles).

<InlineAlert slots="text" variant="info"/>

Remember that the `fromPostscriptName()` method is **asynchronous**. The promise resolves to an `AvailableFont` instance only for fonts that the user has permission to use for editing content; otherwise, it will resolve to `undefined`.

### Example: Set Fonts in a range.

Let's now change the font of the first three characters in a TextNode. Please note that although you're allowed to set the font as the only style, the font object itself must contain all the properties, as the following code snippet demonstrates.

```js
// sandbox/code.js
import { editor, fonts } from "express-document-sdk"; // 👈 fonts import

// Assuming the user has selected a text frame
const textNode = editor.context.selection[0];

// Getting a new font object
const lato = await fonts.fromPostscriptName("Lato-Light");
if (!lato) return; // in case the user isn't entitled to use this font

// ⚠️ Queueing the edit
editor.queueAsyncEdit(() => {
  textNode.fullContent.applyCharacterStyles(
    { font: lato, fontSize: 24 },
    { start: 0, length: 3 }
  );
});
```

<InlineAlert slots="header, text" variant="warning"/>

Asynchronous operations

Queuing the `applyCharacterStyles()` method is necessary because `fromPostscriptName()` is asynchronous. This ensures the edit is properly tracked for saving and undo. You can read more about this in the [queueAsyncEdit()](../../../references/document-sandbox/document-apis/classes/Editor.md#queueasyncedit) reference.

### Example: Get all Fonts

A font, regardless of whether accessed via `CharacterStylesRange` or executing `fromPostscriptName()`, exposes the following properties:

- `isPremium`: boolean, indicating whether the font is a Premium Adobe font.
- `availableForEditing`: boolean, indicating whether the user has access or licensing permissions to create or edit content with this font.
- `family`: string, the font family name, as you would find in the Text panel's UI.
- `postscriptName`: string, the PostScript name of the font.
- `style`: string, the style of the font (e.g., "Regular", "Bold", "Italic").

You can log `font` and inspect it to find the actual PostScript name.

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

// Assuming the user has selected a text frame
const textNode = editor.context.selection[0];
const contentModel = textNode.fullContent;

// Get the array of character styles
const existingStyles = contentModel.characterStyleRanges;

// Log the font of the first style
console.log(existingStyles[0].font);
// {
//   isPremium: false
//   availableForEditing: true
//   family: "Source Sans 3"
//   postscriptName: "SourceSans3-Regular"
//   style: "Regular"
// }
```

### Example: Set all Fonts

Similarly to what we've seen with [other styles](#example-set-all-styles), you can set the font in a range by reassigning the `characterStyleRanges` array.

```js
// sandbox/code.js
import { editor, fonts } from "express-document-sdk";

// Assuming the user has selected a text frame
const textNode = editor.context.selection[0];
const contentModel = textNode.fullContent;

const sourceSansBold = await fonts.fromPostscriptName("SourceSans3-Bold");
if (!sourceSansBold) return;

// Get the array of character styles
const existingStyles = contentModel.characterStyleRanges;

// Set the font for all styles
existingStyles.forEach((style) => {
  style.font = sourceSansBold;
});
// Alternatively, you could set the font for a specific style range
// existingStyles[0].font = sourceSansBold;

// Reassign the array to apply the style changes
editor.queueAsyncEdit(() => {
  contentModel.characterStyleRanges = existingStyles;
});
```

<InlineAlert slots="text" variant="warning"/>

Since we're dealing with asynchronous operations, we're queuing the edit to ensure it's properly tracked for saving and undo, as we did for [setting other styles](#example-set-all-styles)

## Apply Paragraph Styles

Paragraph styles can be applied to a TextNode using the [`fullContent.applyParagraphStyles()`](../../../references/document-sandbox/document-apis/classes/TextContentModel.md#applyparagraphstyles) method. This method applies one or more style properties to entire paragraphs within the specified range, while leaving any style properties that are not provided unchanged. In contrast to directly setting the [`paragraphStyleRanges`](../../../references/document-sandbox/document-apis/classes/TextContentModel.md#paragraphstyleranges) property—which resets any unspecified properties to their defaults—using `applyParagraphStyles()` lets you update only the desired aspects of the style.

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently **_experimental only_** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../references/manifest/index.md#requirements) section of the `manifest.json`.

The available properties are defined by the [`ParagraphStylesInput`](../../../references/document-sandbox/document-apis/interfaces/ParagraphStylesInput.md) interface and include:

- **lineSpacing**: Specifies the spacing between lines (leading), expressed as a multiple of the font’s default spacing (e.g. 1.5 means 150% of normal).
- **spaceBefore**: Sets the space (in points) before a paragraph.
- **spaceAfter**: Sets the space (in points) after a paragraph.
- **list**: Configures list styles (ordered or unordered) for the paragraph. When specifying list styles, you provide the settings via either the [`OrderedListStyleInput`](../../../references/document-sandbox/document-apis/interfaces/OrderedListStyleInput.md) or [`UnorderedListStyleInput`](../../../references/document-sandbox/document-apis/interfaces/UnorderedListStyleInput.md) interface.

Paragraphs are defined by newline characters (`\n`), so the style ranges should align with these boundaries. The method accepts an optional range—an object with `start` and `length` properties—that determines which portion of the text content will be updated. If no range is provided, the styles will be applied to the entire text content flow.

<InlineAlert slots="header, text" variant="warning"/>

Style Ranges and Text Edits

For the moment, replacing the `fullContent.text` will result in applying the style from the first range to the whole text. This behavior is subject to change in future releases.

### Example: Set Styles in a Range

In this example, we modify the styles for a specific paragraph (the first 20 characters) by updating the line spacing and adding an ordered list style.

```js
// sandbox/code.js
import { editor, constants } from "express-document-sdk";

// Assuming the user has selected a text frame
const textNode = editor.context.selection[0];

// Apply paragraph styles to the specified range (e.g., the first paragraph)
textNode.fullContent.applyParagraphStyles(
  {
    lineSpacing: 1.5, // 150% of normal line spacing
    spaceBefore: 12, // 12 points before the paragraph
    spaceAfter: 8, // 8 points after the paragraph
    list: {
      type: constants.ParagraphListType.ordered,
      numbering: constants.OrderedListNumbering.doubleZeroPrefixNumeric,
      prefix: "",
      postfix: ".",
      indentLevel: 2, // Indent level for the list
    },
  },
  {
    start: 0,
    length: 20,
  }
);
```

### Example: Get All Styles

To view the paragraph styles currently applied to a TextNode, you can access the [`fullContent.paragraphStyleRanges`](../../../references/document-sandbox/document-apis/classes/TextContentModel.md#paragraphstyleranges) property. This property returns an array of [`ParagraphStylesRange`](../../../references/document-sandbox/document-apis/interfaces/ParagraphStylesRange.md) objects, each representing the style configuration for a contiguous block of text (i.e. a paragraph).

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

// Assuming the user has selected a text frame
const textNode = editor.context.selection[0];
const contentModel = textNode.fullContent;

// Retrieve and log the paragraph style ranges
const paragraphStyles = contentModel.paragraphStyleRanges;
console.log("Paragraph Styles: ", paragraphStyles);
```

### Example: Set All Styles

You can also update paragraph styles for the entire text content by modifying the array returned by [`paragraphStyleRanges`](../../../references/document-sandbox/document-apis/classes/TextContentModel.md#paragraphstyleranges). In this example, we update the `spaceAfter` property for all paragraphs.

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

// Assuming the user has selected a text frame
const textNode = editor.context.selection[0];
const contentModel = textNode.fullContent;

// Get the current paragraph style ranges
const existingStyles = contentModel.paragraphStyleRanges;

// Update each range (for instance, set spaceAfter to 10 points)
existingStyles.forEach((range) => {
  range.spaceAfter = 10;
});

// Reassign the modified array to apply the changes
contentModel.paragraphStyleRanges = existingStyles;
```

### Example: Reapply Styles

When you update the text content, paragraph boundaries may change. To preserve your custom paragraph styles, save the current style ranges, modify the text, and then reapply the saved styles.

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

// Assuming the user has selected a text frame
const textNode = editor.context.selection[0];
const contentModel = textNode.fullContent;

// Save the current paragraph style ranges
const savedParagraphStyles = contentModel.paragraphStyleRanges;

// Replace the text content
contentModel.text = "New text content\nwith updated paragraphs";

// Reapply the saved paragraph styles
contentModel.paragraphStyleRanges = savedParagraphStyles;
```

<InlineAlert slots="text" variant="warning"/>

If the updated text does not match the original paragraph boundaries, some styles may not be reapplied as expected. This is a temporary limitation until automatic preservation of paragraph styles is implemented.

## Deal with Text Flow

With the introduction of "Text Flow" in Adobe Express (allowing content to move freely between multiple text frames), the concept of a text node had to be separated from text content.

The `fullContent` property _points to_ a [`TextContentModel`](../../../references/document-sandbox/document-apis/classes/TextContentModel.md) object, which contains the actual text content that multiple `TextNode` instances can share.

### Example

```js
// sandbox/code.js
import { editor } from "express-document-sdk";

// Assuming the user has selected a text frame that contains
// text spanning to multiple text nodes
const selectedTextNode = editor.context.selection[0];

// Log all the text nodes that share the same TextContentModel
for (const textNode of selectedTextNode.fullContent.allTextNodes) {
  console.log(textNode);
}
```
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Video
  - Media
  - mp4
  - addVideo
title: Use Videos
description: Use Videos.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Use Videos

## Import videos into the page

Similarly to Images and Audio, you can add Videos to the page using the [`addVideo()`](../../../references/addonsdk/app-document.md#addvideo) method of the `addOnUISdk.app.document` object, which expects a `Blob` object as an argument.

### Example

```js
// sandbox/code.js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  try {
    const videoUrl =
      "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a11/a11-16mm-mag-c.mp4";
    const video = await fetch(videoUrl);
    const videoBlob = await video.blob();

    await addOnUISdk.app.document.addVideo(
      videoBlob // 👈 Blob object
    );
  } catch (e) {
    console.error("Failed to add the video", e);
  }
});
```

Please note that you can use `fetch()` also to get videos that are local to the add-on; in this case, you can use paths relative to the add-on's root.

```js
// sandbox/code.js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  try {
    // 👇 Local video
    const videoUrl = "./7744218-uhd_2732_1440_25fps.mp4";
    const video = await fetch(videoUrl);
    // ... same as before
```

<InlineAlert slots="header, text" variant="info"/>

Video file requirements

Please refer to [this page](https://helpx.adobe.com/au/express/create-and-edit-videos/change-file-formats/video-quick-actions-requirements.html) to know more about the file formats support and size/length requirements for videos.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - User info
  - userId
  - isPremiumUser
  - currentUser
title: Identify Users
description: Identify Users.
contributors:
  - https://github.com/undavide
  - https://github.com/hollyschinsky
---

# Identify Users

## Get the User ID

You can leverage the [`addOnUISdk.app.currentUser`](../../../references/addonsdk/app-currentUser.md) object to obtain the information for the currently logged-in user. Two asynchronous methods are available: `userId()` returns an anonymized ID that is unique to the user and persistent, and `isPremiumUser()` returns a boolean value indicating whether the user has a premium subscription with Adobe Express or not.

### Example

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  const userId = await addOnUISdk.app.currentUser.userId();
  const isPremium = await addOnUISdk.app.currentUser.isPremiumUser();

  console.log(`Current Userid:\n${userId}`);
  // Current Userid:
  // 3cda976828a4a90d13b0f38b1f8a59b1d6845cabfc48037fb30bb75d3ef67d36`

  console.log(`Is Premium User: ${isPremium}`);
  // Is Premium User: false
});
```

## Use Cases

The `userId()` serves as a unique identifier that you can use to track whether a user is a free or paid subscriber to your add-on. By storing this ID in your database, you can manage user-specific features and permissions, allowing your add-on to unlock premium functionalities or restrict access based on their subscription status. Similarly, `isPremiumUser()` return value can be used to tailor the user experience, for example suggesting Adobe Express premium features..

Please refer to the [`addOnUISdk.app.currentUser`](../../../references/addonsdk/app-currentUser.md) and the [licensed-addon code sample](/samples.md#licensed-addon), which shows how you can utilize the hash of the user ID to integrate your add-on with licensing and payment services.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: About our How-to guides
description:
contributors:
  - https://github.com/hollyschinsky
  - https://github.com/undavide
---

# About our How-to guides

The following guides contain a set of common use cases and accompanying code snippets that will help you quickly implement a wide variety of features in your add-ons.

You're encouraged to use the [Code Playground](../getting_started/code_playground.md) to test each one of them. We're constantly adding new how-tos, so make sure to check back often! If you're looking for more extensive examples, you can also look at our [code samples](https://developer.adobe.com/express/add-ons/docs/samples/). The [SDK References](https://developer.adobe.com/express/add-ons/docs/references/addonsdk/) can be used to find all of the objects, methods, properties and events supported for building add-ons. A list of the available topics can be found below:

<!-- - Add-on Development
  - [Debugging](./how_to/debugging.md)
  - [Imports and Constants](./how_to/imports_and_constants.md)
  - [Listening to Events](./how_to/listening_to_events.md)
  - [Add-on UI and Document API communication](./how_to/ui_document_api_communication.md) -->

- Authentication & Authorization
  - [Use OAuth 2.0](./how_to/oauth2.md)
- Data & Environment
  - [Store Data](./how_to/local_data_management.md)
  - [Theme & Locale](./how_to/theme_locale.md)
- UI & Interaction
  - [Use Drag & Drop](./how_to/drag_and_drop.md)
  - [Use Modal Dialogs](./how_to/modal_dialogs.md)
- Use Design Elements
  - [Use Text](./how_to/use_text.md)
  - [Use Geometry](./how_to/use_geometry.md)
  - [Use Color](./how_to/use_color.md)
  - [Use Images](./how_to/use_images.md)
  - [Use Videos](./how_to/use_videos.md)
  - [Use Audio](./how_to/use_audio.md)
  - [Use PDF and PowerPoint](./how_to/use_pdf_powerpoint.md)
  - [Group Elements](./how_to/group_elements.md)
  - [Position Elements](./how_to/position_elements.md)
- Use Metadata
  <!-- - [Authoring Adobe Express Content](./how_to/authoring_adobe_express_content.md) -->
  - [Document Metadata](./how_to/document_metadata.md)
  - [Page Metadata](./how_to/page_metadata.md)
  - [Element Metadata](./how_to/element_metadata.md)
- Exporting & Output
  - [Create Renditions](./how_to/create_renditions.md)
  - [Manage with Premium Content](./how_to/premium_content.md)
- User Info
  - [Identify users](./how_to/user_info.md)

Feel free to reach out and suggest new ones that you would find helpful!
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: Guides
description: Useful guides to aid in the development of Adobe Express add-ons, including common use case examples, CORS handling and other development-related resources.
contributors:
  - https://github.com/hollyschinsky
---

# Overview

This section provides a set of guides to help you in the development stage of your add-on.

## Introduction

In these guides, you'll find detailed information about [implementing common use cases](./how_to.md), [web frameworks, libraries and bundling](./frameworks-libraries-bundling.md), [performance tips](./performance.md), and more.

Begin by watching this short video below which provides an introduction to some of the add-on features and APIs available for use in your add-ons.<br/><br/>

<div style="display: flex; justify-content: center;">
  <iframe width="560" height="315" src="https://www.youtube.com/embed/HHnX5o8CxHU?si=4w4KvQVdkl8r5BZZ" title="Building Add-on Features" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>
# Performance Tips and Techniques

This page covers a list of tips for optimizing your code to help you build high-performance add-ons.

## JavaScript Performance Tips

### Use asynchronous programming

Use asynchronous programming techniques like callbacks, promises, and async/await to avoid blocking the main thread and improve performance. An example of each approach is given below:

**1. Asynchronous programming using callbacks**<br/>
Callbacks are the simplest form of asynchronous programming in JavaScript. Instead of waiting for a function to complete, you pass a callback function to the function that will be called when the operation is complete.

```js
function fetchData(callback) {  
  // perform some asynchronous operation  
  // ...  
  // call the callback function with the result  
  callback(result);  
}  
  
// call the function with a callback  
fetchData(function(result) {  
  // handle the result  
});  
```

**2. Asynchronous programming using promises**<br/>
Promises are a more powerful form of asynchronous programming that allow you to chain operations and handle errors more easily.

```js
function fetchData() {  
  return new Promise(function(resolve, reject) {  
    // perform some asynchronous operation  
    // ...  
    // resolve the promise with the result  
    resolve(result);  
    // or reject the promise with an error  
    reject(error);  
  });  
}  
  
// call the function and handle the result with a promise  
fetchData().then(function(result) {  
  // handle the result  
}).catch(function(error) {  
  // handle the error  
});  
```

**3. Asynchronous programming using async/await**<br/>
Async/await is a newer feature in JavaScript that allows you to write asynchronous code that looks like synchronous code. For example:

```js
async function fetchData() {  
  // perform some asynchronous operation  
  // ...  
  // return the result  
  return result;  
}  
  
// call the function and handle the result with async/await  
async function handleData() {  
  try {  
    var result = await fetchData();  
    // handle the result  
  } catch (error) {  
    // handle the error  
  }  
}  
```

<InlineAlert slots="text" variant="success"/>

Asynchronous programming can be more complex than synchronous programming, and requires careful handling of errors and callbacks. However, it can greatly improve the performance and responsiveness of your JavaScript code, and is the recommended practice for developers building add-ons.

### Cache frequently accessed data

Cache frequently accessed data to reduce the number of times it needs to be computed.

### Use efficient data structures

Use efficient data structures like `maps` and `sets` instead of arrays for faster access and better performance.

### Minimize DOM manipulation

Accessing and manipulating the DOM is one of the slowest operations in JavaScript. Minimize DOM manipulation by grouping DOM changes together and using techniques like document fragments or virtual DOM.

### Use event delegation

Instead of attaching an event listener to every element, use event delegation to attach a single event listener to a parent element and handle events for all its child elements.

### Optimize loops

Optimize loops by minimizing the number of times you access an array's length property, using `while` loops instead of `for` loops, and breaking out of loops early when possible.

### Use lazy loading

Use lazy loading to load resources only when they are needed, reducing initial page load time.

### Minimize the use of global variables

Minimize the use of global variables to reduce the risk of naming collisions and improve performance.

### Reduce HTTP requests

Minimize the number of HTTP requests by combining multiple files into one, using image sprites, or using data URLs for small images.

## React Performance Tips

This section outlines some performance tips for writing React code.

### Use the virtual DOM

React uses a virtual DOM to minimize the number of updates needed to render changes to the user interface. Make sure to use React's built-in components and lifecycle methods to take advantage of this feature.

### Minimize component updates

Minimize component updates by using `shouldComponentUpdate()` or `React.memo()` to prevent unnecessary re-renders of components.

### Avoid unnecessary state changes

Avoid unnecessary state changes by only updating state when necessary and using setState() correctly.

### Use `PureComponent`

Use [`PureComponent`](https://react.dev/reference/react/PureComponent) instead of regular components to automatically implement `shouldComponentUpdate()` and improve performance.

### Use keys for lists

Use keys for lists to help React identify which items have changed and minimize unnecessary re-renders.

### Use lazy loading

Use lazy loading to load components or resources only when they are needed, reducing the initial page load time.

### Avoid excessive looping

Avoid excessive looping by using techniques like `map`, `filter`, and `reduce`.

### Use memoization

Use memoization to cache the results of expensive calculations or functions and avoid unnecessary re-computation.

### Use React Profiler

Use [React Profiler](https://react.dev/reference/react/Profiler) to identify performance bottlenecks in your code and optimize them.

### Use code splitting

Use code splitting to split your code into smaller chunks and load only the necessary code for a given page or component.

### Avoid unnecessary `props`

Avoid unnecessary `props` by passing only those necessary to child components, and use destructuring to avoid passing unnecessary data.

By following these tips, you can optimize your React code and improve its performance. Remember to test and measure the performance of your code to identify areas for optimization.

## Performance Testing

Be sure to test your add-on code and measure its performance to identify areas for optimization and ensure that your changes have a positive impact on performance. There are several ways to measure the performance of your JavaScript code, some are listed below for reference:

### `console.time()` and `console.timeEnd()`

Use the `console.time()` and `console.timeEnd()` methods to measure the time it takes for a block of code to execute.

```js
console.time('myFunction');  
myFunction();  
console.timeEnd('myFunction');  
```

### `performance.now()`

Use the `performance.now()` method to measure the time it takes for a block of code to execute with high precision.

```js
const t0 = performance.now();  
myFunction();  
const t1 = performance.now();  
console.log(`myFunction took ${t1 - t0} milliseconds.`);  
```

### Chrome DevTools

Use the performance profiler in Chrome DevTools to identify performance bottlenecks in your code. The profiler can show you a detailed breakdown of the time spent in each function, as well as information about memory consumption.

#### Task Manager

The Chrome Task Manager displays the CPU, memory, and network usage of each open tab and plug-in, and allows you to kill an individual process similar to the Windows Task Manager or MacOS Activity Monitor. To open the Task Manager, go to the Chrome triple dot menu -> **More Tools** -> **Task Manager**:

![Task Manager](img/menu_task_mgr.png)

There you can locate the memory consumption of the OS process spawned specifically for the add-on iframe, like below:

![Task Manager](img/task-mgr.png)

#### Memory Consumption Monitoring

The Chrome **Memory** tab can be used to help solve memory issues, including debugging of JavaScript memory leaks. You can also use it to see the memory consumption of the JavaScript context created by the add-on iframe specifically, as shown below:

![Memory Consumption](img/memory-consumption.png)

### Lighthouse

Use [Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/), an open-source tool from Google, to audit performance and identify areas for optimization while your add-on is loaded. Lighthouse can provide suggestions for improving page load time, reducing the size of resources, and optimizing JavaScript code.

### Benchmark.js

Use [Benchmark.js](https://benchmarkjs.com/) to benchmark different implementations of a function or compare the performance of different libraries. Benchmark.js provides a simple and powerful way to measure the performance of your code in a standardized way.

By measuring the performance of your JavaScript code, you can identify areas for optimization and ensure that your code is running efficiently. Use these techniques to test and optimize your code to achieve the best possible performance.
# Developer Brand Guidelines

## Overview

The [Adobe Express Developer Program brand guidelines](https://developer.adobe.com/express/embed-sdk/docs/assets/34359598a6bd85d69f1f09839ec43e12/Adobe_Express_Partner_Program_brand_guide.pdf) provide important information on branding, including:

- How to brand your add-on
- How and when to use Adobe logos and branding
- How to refer to Adobe products and terms
- Use of acronyms and abbreviations
- Guidelines for social media

Refer to these [Developer Brand Guidelines](https://developer.adobe.com/express/embed-sdk/docs/assets/34359598a6bd85d69f1f09839ec43e12/Adobe_Express_Partner_Program_brand_guide.pdf) often when creating and designing your add-on.
# Generative AI Guidelines

This set of guidelines gives you the latest information on how to meet Adobe’s requirements around Generative AI.

## Introduction

Our Generative AI guidelines include:

- Listing guidelines
- Content generation guidelines, including disclaimer guidelines
- Recommendations for add-ons using generative AI technology

We will edit and update this guide as our requirements and the technology evolve.

## Overview

The rise of Generative AI offers potential benefits for add-ons, particularly in facilitating content creation and accelerating workflows. Adobe requires that users be able to choose whether they want to try add-ons that employ Generative AI technology. This means that add-ons must clearly state upfront when they use generative AI technologies.

We created these guidelines to assist any developers who wish to take advantage of Generative AI in their add-ons, to make sure they do so in accordance with Adobe standards.

We have split this section into:

- [Requirements](./requirements.md) (which must be followed)
- [Recommendations](./recommendations.md) (which are suggestions we encourage for best practice)

<InlineAlert slots="text" variant="warning"/>

**If we receive reports of abuse, we may elect to remove an add-on whether it is private or public.**
# Recommendations

Our best practices for Generative AI add-ons

## Overview

The following recommendations are suggestions which we think will help you to optimize the user experience of your add-ons.

However, we will not remove an add-on if we find these recommendations are not implemented.

## Create content quickly

Users expect to be able to quickly add assets to their documents quickly and efficiently.

While generative AI technologies often take several seconds to yield results, you should ensure that users can start to see results after a short period of time (**ideally less than fifteen seconds**).

You should also display an appropriate spinner, shimmer, or other appropriate animation while results are being generated, so that users know that the process is still underway.

You might want to consider quickly returning a single image before generating variations as well.

Add-ons that take too long to generate content are not likely to see repeat use.

## Share information about your AI ethics position

If your add-on leverage generative AI technologies, you should provide information to the user about how models are trained and used from an ethical perspective.

While your ethics don’t have to match Adobe’s perfectly, users should be able to learn about your ethical standards and how these standards apply to your use of AI.

## Share information about how your add-on uses generative AI

It’s pretty clear how an add-on that generates an image from a text prompt leverages generative AI.

But there are other workflows where it might not be clear that generative AI is used, why it is used, and how it is used to facilitate a given workflow.

Users should be provided with information about how and why your add-on leverages generative AI so they can understand its potential applications and limitations.

## Set clear expectations with your users about what is acceptable and what is not

You might have additional requirements regarding acceptable content. Perhaps you want to introduce additional content restrictions beyond the Adobe requirements.

Be sure to communicate these to your users.

These requirements can be listed in any number of locations:

- In the add-on itself
- In the add-on’s description
- As part of any of the links you provide when you submit an add-on to the marketplace (including terms of use or how your add-on uses AI).

## Provide a mechanism for reporting inappropriate content

No content filter or classifier is perfect, and it’s possible that some restricted content might be generated unintentionally, even with a safe prompt.

You may provide your users with a mechanism for alerting you when this happens, so that you can take appropriate action to ensure that similar content isn’t generated in the future.

Users can also use the “Report Abuse” feature inside Adobe Express to report content, but this report will only be sent to Adobe.

**If we receive a significant amount of abuse reports, we may remove your add-on for the safety of our users.**

## If you remove generated content or prevent content from being generated, be clear as to why

Be sure to provide a notice to your users about why your add-on couldn’t generate content, or why an output asset might have been removed.

You don’t need to go into details, but users shouldn’t be faced with blank content or terse, indecipherable error messages.

You can use the Firefly web app or Text-to-image features in Adobe Express as a good guide on how to do this.

## Haven’t found what you’re looking for? Let us know

These recommendations are a “living document” and will be updated over time, as our guidelines - and the technology itself - evolve. If you have any questions about a specific case or issue, or would like to learn more about our requirements, please [contact us](mailto:cc-extensibility-genai-integration-support@adobe.com).
## Listing requirements

Your add-on's listing must be clear that generative AI is being used. During submission of your add-on, you'll be prompted to select if your add-on uses generative AI. If your add-on does so, in any capacity, you must answer in the affirmative. This will ensure that users are properly informated that your add-on utilized generative AI for some or all of its features.

## Content generation requirements

Content created by your add-on must adhere to [Adobe’s General Terms of Use](https://www.adobe.com/legal/terms.html) and the [Developer Terms of Use](http://www.adobe.com/go/developer-terms).

Specifically:

* Your add-on must not generate illegal content.
* Your add-on must leverage filtering technologies and must test your add-on to ensure that illegal content is not generated.
* Before an add-on leveraging generative AI is approved for publication, you may be asked to certify that you have read these guidelines and agree to abide by them.

If your add-on is found to be generating illegal content, your add-on will be removed.

### Disclaimer requirements

If your add-on generates text or code, your add-on must remind the user that the content generated may be inaccurate. Users should always review the generated content with trusted sources before publishing the content or executing any code.  Because every use of AI is different, Adobe doesn't provide a one-size-fits-all example, but there are several examples in the generative AI ecosystem that should provide good examples.

### Use cases that don't require certification

Add-ons that meet the following criteria do not require the add-on's developer to submit a self-certification of compliance with our content generation requirements:

* Your add-on is privately listed (**NOTE:** We may still elect to remove your privately listed add-on if we receive credible reports of abuse)
* AI Models that the user installs and runs locally on their device (that is, models that are not included within the add-on bundle)
* Text-to-speech using Generative AI (provided the text is supplied by the user)
* Instrumental music or sound effects created using Generative AI (where there are no lyrics)

## Check back frequently!

These requirements are a “living document” and will be updated over time, as our guidelines - and the technology itself - evolve. If you have any questions about a specific case or issue, or would like to learn more about our requirements, please [contact us](mailto:cc-extensibility-genai-integration-support@adobe.com).
# Accessibility

Adobe products and add-ons should be accessible to users with a range of needs.

## Overview

We believe Adobe products and add-ons should be accessible to users with a range of needs. Follow the guidelines outlined below to make your add-on more accessible.

<InlineAlert slots="text" variant="success"/>

For more information, check [Adobe’s Accessibility guidelines](https://www.adobe.com/accessibility.html).

## Accessibility standards

Your add-on should meet accessibility guidelines to ensure it can be used by people with disabilities. This could be [WCAG 2.0](https://www.w3.org/TR/WCAG20/) or higher.

## Keyboard accessibility

Your add-on’s user interface should provide proper mouse and keyboard focus indicators, and allow for easy navigation and interaction using only a keyboard.

## Alt-text

Your add-on should provide alternative text for images and labels for form fields, as well as other accessibility features which assist users with visual impairments and other disabilities.

## Contrast and fonts

Your colors, contrast and fonts should be easily readable by users with visual impairments, and meet accessibility standards.

## Readability

Your text and commands should be simple and understandable. This is useful for users with dyslexia, as well as those who do not speak English as a first language, and those who are performing actions while multitasking, distracted or under pressure.
# Authenticating Users

Users must be able to log in and out of the add-on seamlessly. Ensure that all of these functions work effectively before submitting for review.

## Sign-up functionality

Users must be given a seamless sign-up option, particularly when logging in is mandatory. They must be able to complete this process in a new window if they wish.

## Logout functionality

Users must be able to logout easily, using a button or link that is simple to locate.

## Popups and blockers

Sometimes users may think that the add-on is not responding properly when they try to sign in, but the sign-in popup is actually being blocked by the browser’s popup blocker.

This is why add-ons that use OAuth flows must always indicate to users when a popup window has been blocked. This can be done by displaying a message in the add-on UI or on the webpage.

**NOTE:** The API returns `POPUP_BLOCKED` when a popup window is blocked during the OAuth flow. This will help you detect when a popup has been blocked.

## Test credentials

If a login or license key is required to access any paid features, you must provide test credentials to reviewers so that they can view all aspects of the add-on.
# Compatibility

Your add-on will help the user to make the most of their Adobe Express experience, so it’s important that it feels like part of their workflow.

## Conflicts

Your add-on must not conflict with any other installed add-ons in Adobe Express.

## Different systems and browsers

Your add-on must work on the same [browsers and operating systems supported by Adobe Express](https://helpx.adobe.com/express/system-requirements.html).

Add-ons must perform well on machines of varying performance characteristics. Adobe Express is supported on Chromebooks and machines with low resolution and limited memory. Don't assume that your users have powerful computers.

Add-ons are not currently supported on mobile devices. This will change in the future, so you should ensure that your add-on adheres to responsive design principles and can adapt to different panel sizes so that you can be prepared when mobile support is available.
# Content Requirements

In the interests of user safety and acceptable standards, add-ons must not:

- Contain or generate illegal content (such as CSAM, content that encourages illegal drug use, etc).
- Contain or generate adult content (such as sexual content, nudity, gore, intense violence, or strong language).
- Contain or generate hate speech or speech that promotes violence or bullying or cruel behavior to anyone.
- Generate content that promotes, automates, or relates to highly regulated activities (such as financial advice, medical advice or diagnosis, legal advice or documents, contracts).
- Contain or generate code that could be malicious (such as viruses, malware, spyware, etc.).
- Participate in misinformation/disinformation campaigns.
- Violate intellectual property rights, including copyright, of other persons and companies.
- Automatically perform actions determined by AI that would be destructive or that can’t be undone without explicit user consent..
# Testing for edge cases

Edge cases may affect the performance of your add-on.

## Overview

As well as checking for more expected errors, you must also take the time to search for edge cases that may affect the performance of your add-on.

This includes checking for boundary values or extreme scenarios that may cause issues when your add-on is in general use.

## Handling inputs

Ensure that your add-on can handle edge cases such as empty inputs, long inputs or inputs with special characters.

## Boundary values

Your add-on should also be able to handle boundary values such as minimum or maximum allowed values without any unexpected behavior.

## Extreme scenarios

Your add-on should be able to cope with extreme situations such as low system resources, poor network conditions, or unexpected interruptions.

## Tab navigation

Users often use tab navigation to make their way through websites and applications. This is particularly true of users with disabilities who rely on keyboard navigation.

Please ensure that add-ons do not interfere with - or override - tab navigation.
# Features

Some elements to bear in mind when testing the features of your add-on before submission.

## Stability

Make sure the add-on does not crash Adobe Express, and operates consistently without stability issues.

## Storing user data

Your add-on should only store necessary information on the user’s machine. If it stores a lot of data, it must be able to handle any errors that arise from exceeding storage quotas.

## Loading indicators

When loading takes a noticeable amount of time, a loading indicator should be displayed to provide visual feedback. If an operation takes a considerable amount of time and blocks the use of the add-on or Adobe Express, the add-on should provide an affordance that allows the user to cancel the operation.

## Generating renditions

Where the add-on generates renditions of user content, it must provide some sort of progress indicator.

This reassures the user that the process is ongoing, and that the add-on has not simply stopped responding.

## Text boxes

Any text boxes must support English characters, numbers and special characters as expected.

## Importing images and videos

Your add-on must be able to smoothly import any media required for design or operation.

## “Drag and Drop” functionality

If the add-on allows users to add content to the document, it should support drag and drop functionality. This allows users to select an image from the add-on and drop it in the desired location in a document.

## “Single-click to Add” functionality

Any add-on where content can be added to a document should also support the option to add an image with a single click. This means that users can click on the desired location to integrate an image.

## Support for both options above

You are encouraged to support both “Single-click to Add” and “Drag and Drop” functionality wherever possible. There may be some exceptions in cases where “Drag and Drop” is technically not feasible. If “Drag and Drop” is not supported, ensure that you communicate this to the user to avoid confusion.

## Navigation

The user must be able to navigate through all menus and screens, without feeling “stuck”. If they find themselves on the wrong screen, they should be able to navigate out (for example, using a “back” or “menu” button).

## Online-offline-online

If the user’s internet connection drops out during use, the add-on must be able to resume normal operation after reconnecting.

This means:

- The reconnection process should occur seamlessly and gracefully.
- The transition from online to offline and online again should not break the add-on in any way.
- If the add-on does fail to work for whatever reason, an appropriate error message should be displayed.
- When the user is offline, the add-on should not affect the performance or stability of the application.
# Overview

This section provides a set of guides to help you in the distribution stage of your add-on.

## Introduction

The general guidelines that can be found in this section cover a variety of areas including [acceptable content](./content.md), [user interface guidelines](./user_interface.md), [listing metadata](./listing.md), [feature functionality](./features.md) and testing guidelines (e.g., [compatibility](./compatibility.md), [usability](./usability.md), [accessibility](./accessibility.md), [performance](./performance.md)) and more.

## Testing

Testing is an important part of the add-on creation process. It ensures that the add-on is free from bugs, works as intended, and performs as smoothly as possible.

We strongly recommend that you test your add-on rigorously before submitting it for review, to avoid rejection or delays in submission

## Important Resources

The following list of guidelines should also be carefully reviewed as they provide important information you'll need to know before submitting your add-on to our marketplace.

- [Developer Brand Guidelines](../brand_guidelines.md/)
- [Generative AI Guidelines](../genai/index.md)
- [Monetization Guidelines](../monetization.md)
# Listing Your Add-on

Your listing should provide valuable information about what your add-on does, and why people should use it.

<AnnouncementBlock slots="heading, text, button" />

Are you an existing developer?

Action required: Add trader details to continue EU distribution.

[Add trader details now.](https://new.express.adobe.com/add-ons?mode=submission)

## Listing metadata

Your listing metadata provides Adobe and users with details about your add-on. Follow the guidelines below to ensure your listing clearly describes everything you want your users to know about your add-on.

<InlineAlert slots="text" variant="info"/>

**NOTE:** Please avoid the use of emojis in your listing metadata as the user interface does not allow them.

Refer to our [Developer Brand Guidelines](../brand_guidelines.md) for more information.

### Naming your add-on

Consider using a simple name that is easy to spell, but distinctive enough to find using search.

The name should give users an idea of what the add-on does. For example, using a company name may be clear to you, but not to other users. Try to avoid using a long name where possible.

When listing an add-on, you must not use the word “Premium” to describe your upgrade options, as this should only be used in relation to the [Adobe Express Premium Plan](https://www.adobe.com/express/pricing).

### Your add-on description

Let your users know clearly and concisely what your add-on does.

Think of this as your elevator pitch. Use this space to concisely describe the functionality and benefits of your add-on, using tone and language which is appropriate to your add-on and your own personal or brand style.

If your add-on generates assets via AI or imports assets from an asset repository, you should include accurate and up-to-date information about usage rights here.

Consult our [Generative AI guidelines](../genai/) for more information.

### Your summary

Use the summary section to concisely outline the features and functionality of the add-on. Think of this as the tagline to your add-on.

### Support email

You must provide a valid email address so that we can contact you for support. End users will not see this email address.

### Screenshots

Your screenshots should accurately represent the functionality and appearance of the add-on, such as key features and important user steps. It is essential to refrain from including images that could potentially mislead users or are deemed inappropriate.

### Your icon

Use an original icon that complies with our [Developer Brand Guidelines](https://developer.adobe.com/express/embed-sdk/docs/assets/34359598a6bd85d69f1f09839ec43e12/Adobe_Express_Partner_Program_brand_guide.pdf). Consider using a design that illustrates what the add-on does.

Your icon should be simple and distinctive, and must be suitable for viewing on different devices and browsers.

### Help URL

Include a link to a valid webpage that provides accurate and relevant information about the add-on’s usage and functionality.

It is recommended to add support for common queries or user issues.

### Privacy Policy/License Agreement

You must include details of your privacy policy and contractual terms applicable to the use of your add-on(s). Do not include text that violates our [Developer Brand Guidelines](https://developer.adobe.com/express/embed-sdk/docs/assets/34359598a6bd85d69f1f09839ec43e12/Adobe_Express_Partner_Program_brand_guide.pdf).

### Keywords

It is recommended to include keywords to categorize your add-on and make it easier to find. Multi-word keywords are allowed (but remember: spaces count toward the overall character limit for keywords).

Try to include keywords which reflect the features and purpose of the add-on, which the user is likely to search for. Spell out keywords in full. You must not include any words that are abusive and/or derogatory.

### Release section

Use this section to include details of any updates, fixes and improvements you have made to the add-on since launch.

These notes must accurately describe the changes made, and be written in such a way that they make sense to the user.

## Publisher profile

Completing your publisher profile can be helpful in making your app look more professional, interesting and trustworthy.

Ensure that all content adheres to our [Developer Brand Guidelines](https://developer.adobe.com/express/embed-sdk/docs/assets/34359598a6bd85d69f1f09839ec43e12/Adobe_Express_Partner_Program_brand_guide.pdf).

### Your publisher name

Create a unique name that reflects your personality. It must not contain inappropriate words or phrases.

### Your description

Use your description to explain a little more about you, including any areas you may specialize in.

### Your logo

Your publisher logo must be original. You must not use the Adobe logo, or any product icons or images, without authorization.

### Your website URL

Include a website so that people can find out more about you. This should successfully open your own website. Specifically, according to page 5 of the [Developer Brand Guidelines](https://developer.adobe.com/express/embed-sdk/docs/assets/34359598a6bd85d69f1f09839ec43e12/Adobe_Express_Partner_Program_brand_guide.pdf) your “...domain name must not include any Adobe trademark or product name.”

For example:

**www.[Your Company name].com/Add-onforExpress**

NOT:

**www.[Your Company name]forAdobeExpress.com**

### Trader details

In accordance with the [European Union Digital Services Act](https://eur-lex.europa.eu/legal-content/EN/ALL/?uri=CELEX:32022R2065) trader requirements, developers who wish to distribute their add-ons in the European Union (EU) must provide additional information in their publisher profile.

<InlineAlert variant="info" slots="header, text1, text2, text3, text4" />

Developer/Trader

The terms **developers/traders** are used interchangeably in this guide.

Any developer who wishes to publish their add-ons in the EU can be identified as a trader.

Checkout our [Know your trader](https://developer.adobe.com/compliance/) guide to understand **why** you must provide these details to make your add-ons available in the EU.

This information will be displayed to only users in the European Union (EU).

Choose **Yes** if you wish to make your add-ons available for users in the EU.

![Trader details](../../img/trader-details.png)

You must provide the following details:

- Business email address​
- Country code and Business telephone number
- Business street address or P.O. box
- City
- State/Province/Region
- ZIP/Postal code
- Country
- Business D-U-N-S number [`optional`]

You must complete and submit your publisher profile in order to submit your first add-on, however this is only a one time thing, unless you decide you need to update for your own reasons.

Any changes to your publisher profile will need to be submitted for approval again.

<InlineAlert variant="warning" slots="header, text1, text2, text3" />

**Are you an existing developer?**

Existing developers can easily update their trader details directly in their [publisher profile](https://new.express.adobe.com/add-ons?mode=submission).

Note that only trader details can be added; other fields cannot be edited by developers.

You must provide trader details by February 16, 2025, to keep your add-on visible and available in Adobe Express for users in the European Union as of February 17, 2025. This trader information will be displayed publicly on your listing detail pages when viewed from EU countries.
# Performance

If you want your add-on to become a key part of a user’s workflow, you must make sure it performs smoothly and efficiently.

## Overview

Your add-on must meet acceptable standards in terms of loading time, response time and utilization of resources. You should also bear in mind that a user’s experience may differ, based on factors such as their network connection.

Below are a few things to consider before submitting for review.

## Crashes

Your add-on must not cause any slowdowns or crashes on Adobe Express.

## System resources

You must ensure your add-on does not consume excessive system resources which may affect the performance of the user’s system, or Adobe Express itself. This includes resources such as CPU and memory.

## Network calls

Your add-on must not make an excessive amount of network calls. You can monitor this by noting the number of network calls made over a certain period, and comparing it to a predetermined threshold.

## Network efficiency

Make sure your add-on is network efficient and does not have any performance issues. You can do this by noting the time it takes to complete a network call and how much data is transferred.

## Network usage

We recommend using network monitoring tools to identify any unexpected or excessive network activity caused by the add-on.

## Network security

Your add-on must not pose any security risks, and network calls must be secure. We require that add-ons use secure protocols, encrypt sensitive data, and implement appropriate authentication and authorization mechanisms.

## Network call logs

Review your network call logs to identify any anomalies or notable patterns in network usage. This helps you identify any issues related to network calls.
## Choosing your idea

Before you start, do a little research on the marketplace to see what other developers are doing, and where you can make an impact.

For example:

- Does my add-on help users to do their work quicker and more effectively?

- Does it streamline the user’s workflow(s)?

- Does my add-on enable users to be more creative, or make their work look better?

- Are there lots of add-ons already doing the same thing on the marketplace?

## Use of AI

Does your add-on leverage AI to generate content or automate workflows? If so, be sure to check out the [Generative AI requirements](../genai/).
# Security

Users must be able to access an add-on without compromising their security or negatively affecting their systems.

Use these guidelines to ensure the security of your add-on.

## Malicious code

Your add-on must not include any malicious code, viruses or malware that could harm a user’s system, or compromise their data.

## User information

Your add-on must not transmit any sensitive user information without prior authorization or consent.

## Vulnerabilities

Your add-on must not feature any currently-known security vulnerabilities, such as unsecured communication channels, weak authentication mechanisms, or potential injection attacks.

We expect developers to maintain their add-on after completion and listing. This includes fixing bugs and addressing any security issues. It is also good practice to be responsive to user feedback and requests.

## Secure coding

Your add-on must follow secure coding practices, such as input validation, as well as proper error handling.
# Usability

Follow these guidelines to make sure that your add-on meets our usability standards before submitting.

## Blending with Adobe Express UI

The add-on should integrate seamlessly with Adobe Express UI,  incorporating commonly-used patterns within the Adobe Express UI to facilitate user navigation.

We also suggest that you use the [Adobe Spectrum theme for Adobe Express](https://spectrum.adobe.com/page/theming/#Resources-for-Spectrum-for-Adobe-Express). It is not mandatory to use [Adobe’s Spectrum libraries](https://spectrum.adobe.com/)  for your add-on, but it can significantly simplify the development process.

## Responsive interface

You must make sure that your add-on’s user interface and controls are responsive, functional and usable across different browsers and screen sizes.

## User inputs

The add-on must provide some sort of response or validation for user inputs, such as confirmation messages for successful actions or error messages for invalid inputs.

## Error messages

Any error messages, warnings or notifications should be clear, informative and helpful to the user.

## Modal dialogs

The add-on should not interrupt the user’s workflow unnecessarily with dialog boxes. These boxes should only be used for important messages. Messages such as “success” notifications should be rendered inside the add-on’s UI panel instead.
# User Interface

Your add-on's user interface should provide a great user experience.

## Your add-on design

When it comes to design, create a layout that aligns with the functionality of your add-on.

However, remember that your users will be accessing your add-on as part of their Adobe Express workflow - so try to make sure they can move seamlessly without coming across anything jarring or counter-intuitive.

We highly suggest leveraging the Spectrum Design System and Spectrum Express theme to create user interfaces that feel similar to the Adobe Express user interface.

We’ve included these guidelines here to help you create a great experience for users. Also refer to our [User interface design guide](../../../design/index.md), which includes a comprehensive set of [UX Guidelines](../../../design/ux_guidelines/introduction.md) to help with your add-on design.

## Display Items

Here are some tips to assist with the layout of your add-on, from display to icons.

### Empty screens

You should avoid including any empty screens in your design. All screens within your add-on should feature at least some information.

### Scroll bars

If your content does not fully fit on a single screen, you should make it clear that the user can scroll to view the remaining content.

### Buttons

All add-on buttons should be displayed correctly, and not overlap with each other.

### Changing between languages

The user interface should still be clear and navigable when the user switches between languages.

They should also be able to input special characters or alphabets from other languages without causing malfunctions.

### Modal dialog

Avoid using dialog boxes that interrupt the user’s workflow, except in important situations.

For example, use the in-panel UI to display things like success messages, rather than a dialog box.

### Icons

Use unique icons to represent the add-on itself, and the features within it. Consider working with a designer to create icons that are clear and distinct.

## Using Adobe icons and phrasing

Follow these guidelines to make sure you are referring to Adobe correctly in your add-on.

For more information on using Adobe brand assets, check our [Developer Brand Guidelines](../brand_guidelines.md).

## Referring to add-ons

Always use the spelling “add-on”, NOT “addon” or “plugin”.

## Referring to Adobe Express

Always use the full name “Adobe Express” when referring to the tool. Do not shorten it to “Express”.

## Using Adobe Icons

We allow and encourage you to use the workflow and UI icons in Spectrum Design within your add-on. However, you must not use any Adobe branding elements, such as the Adobe logo or the “Premium” crown icon for paid items.

## Referring to stock photos

If your copy includes any mention of stock content or assets within Adobe Express, you must refer to it with a lower case “s” (ie. stock).

This avoids confusion with Adobe Stock, which is a separate service.

For example:

***“Discover a wide range of high-quality stock photos in Adobe Express”***

## Localization

All add-ons must provide support for the English language. In addition, you are welcome to create your add-on in any other supported language.

## Functionality for Multilingual UI

You must test your add-on to make sure that the user interface remains intact and functional when you switch between any supported languages.

## Text display

Ensure that changing the language does not result in add-on strings or text content being cut-off or truncated. All text should be visible and displayed appropriately on the add-on in all supported languages.

## Branding your add-ons for monetization

When building your checkout experience to monetize your add-ons, you can use the approved colors, gradients, and iconography to communicate when content or features in your add-on require purchase and when content or features are paid and unlocked.

Carefully review our [monetization brand guidelines](../monetization.md#branding-your-add-ons-for-monetization) to get the latest information on Adobe’s recommendations on branding your add-ons for monetization.
# Introduction

Thank you for joining the community of developers worldwide that are creating add-ons for Adobe Express.

## Guideline Categories

Adobe's goal is to publish high-quality add-ons. With that goal in mind, we’ve created this set of guidelines to give you some tips on best practices, and ensure you take the right steps to get your add-on approved:

- [General guidelines](./general/)
- [Adobe Express Developer Program brand guidelines](./brand_guidelines.md) (aka: "Developer Brand Guidelines" throughout these guides)
- [Monetization guidelines](./monetization.md)
- [Generative AI guidelines](./genai/)
# Monetization Guidelines

Developers who submit to the marketplace can charge users for using their add-ons.

## Overview

Consider whether you want to monetize your add-on at the outset, as it helps you plan your strategy more effectively.

Remember to research the marketplace carefully before you start creating. This will help you learn whether there is a substantial market for a paid add-on and what other developers (if any) are charging for similar solutions.

We’ve created these standards to ensure monetized add-ons provide users with a consistent and reliable experience.

Our monetization guidelines include:

-   [General](#general-guidelines)
-   [Requirements](#requirements-for-monetizing-your-add-ons)
-   [Recommendations](#recommendations-for-monetizing-your-add-ons)
-   [Branding your add-ons](#branding-your-add-ons-for-monetization)

<!-- ## Payment Models

You can choose from a variety of models for your add-on. Take the time to consider which one suits your needs best.

### Free

Users are not charged for adding and using the add-on.

## Freemium

This model offers a basic version for free, but users must upgrade to a paid version for extra features and content. This payment could be a one-time fee or subscription.

Freemium add-ons have a high percentage of acquisition in our marketplace, making this our recommended option.

### Paid

This requires users to pay a fee before using the add-on. You may wish to offer a trial period at the outset, in which users can test out the add-on for a certain period of time before deciding whether to pay.

### Sign-up for service (SaaS)

The add-on requires the user to have access to external services before they can use it.

### Credits

This model asks users to buy credits which can be used for services on the add-on. This can be used for things such as licensing images or trying out Generative AI models. Many add-ons offer users some free credits to start so they can test out the service. -->

## General Guidelines

The sections below provide details on the guidelines developers should be following when monetizing their add-ons.

### Transparency

All add-on developers must be transparent about their pricing and monetization methods. This includes being honest about the price and any recurring fees or additional costs.

Users must be able to:

-   Locate clear instructions on requesting a refund (please place a refund policy on your site).
-   Find a way to cancel any recurring payments, including subscriptions. Manage their payments and update their payment method
-   see how much an add-on will cost them, with no hidden fees or surprise charges.

### Support

You must offer a clear and simple support process for all publicly-listed add-ons. This includes responding to any queries from users regarding access and payments.

### Compliance

You must comply with all applicable laws and regulations. This includes payment regulations, taxation, data privacy, and security.

### Third-party ads

Your add-ons must not contain any third-party advertising, including any ads from Google Ads, Facebook Ads, or any other ad networks.

This applies to the advertising of products and services within the add-on description, and the use of banners in the add-on itself.

### Complying with Express monetization rules

When listing an Adobe Express add-on, you should not use “Premium” to describe your upgrade options.

The word “Premium” should only be used in relation to the Adobe Express Premium Plan, which provides users with extra content, increased storage and more.

### Exporting premium content

Adobe Express allows users that aren't subscribed to a premium version of Adobe Express to experiment with premium content in their documents. When users download or share their document, they'll be prompted to upgrade to a premium plan.

Add-ons must not allow users on a free plan to download, share, or export premium content provided by Adobe Express. When a user on a free plan tries to share or export premium content using your add-on, you must notify the user that they need to upgrade, and inform the user how they can do so. See our [documentation](/guides/develop/use_cases/#premium-content) for more information on how to do this.

## Requirements for monetizing your add-ons

When listing your add-ons for monetization to the public marketplace, you must indicate your add-on's purchase offerings in [the public listing](../public-dist.md#step-8-enter-the-monetization-details).

The following are the supported monetization details currently:

- Free
- One-time payment
- Recurring subscription
- Micro transactions
- Other

<InlineAlert slots="text" variant="info"/>

In all these examples, checkout is handled by the developer outside of Adobe Express.

Here are examples for each payment model based on a Brush Pack add-on in Adobe Express:

| Your selection         | End-user view: add-on listing Payment details                    | Example                                                                                                                                                                                                                                      |
|------------------------|------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Free                   | This add-on does not require any payment.                        | Explore our selection of free brush packs in Adobe Express. Access a range of essential brushes at no cost, perfect for getting started on your creative journey without any upfront payment.                                                |
| One time payment       | Upgrade is available for a one-time purchase.                    | Upgrade to premium brushes with our one-time Brush Pack purchase in Adobe Express. Unlock a diverse range of high-quality brushes for a single payment, granting you unlimited creative potential without any recurring fees.                |
| Recurring subscription | Upgrade is available with a recurring subscription.              | Subscribe to Premium and enjoy continuous access to our extensive library of Brush Packs. For a small monthly fee, access exclusive brushes and receive regular updates with new additions to fuel your creativity.                          |
| Micro-transactions     | You can purchase assets or features individually or in packages. | Customize your creative toolkit with individual brush packs available for purchase in Adobe Express. Choose from a variety of sets or opt for bundled packages to save. Pay only for what you need, empowering you to create without limits. |

## Recommendations for monetizing your add-ons

We recommend following these tips to make your add-on more user-friendly and to avoid potential confusion:

### Offer a choice

We recommend giving users payment options when signing up or upgrading. This includes:

-   A choice of payment methods, such as credit cards, PayPal and other popular alternatives.
-   A choice of payment terms. When signing up for a subscription or pay-as-you-go, provide short and long-term payment options, such as monthly and annual terms.
-   Giving users the chance to try before they buy. Free trials and freemium options can improve sign-up numbers.
-   Avoid using "Pro".
-   Adobe Express caters to non-professional and professional users, so avoid using "pro" in your language.
-   If "pro" refers to a pricing model, make this clear (for example, by saying "Pro Plan").

### Consider user action

Instead of using words such as "premium" or "gold" in your copy, you should try using words that make it clear what the user needs to do.

Words such as "upgrade" or "subscribe" are clearer and more user-friendly. For example, instead of:

❌ *"You're using the trial version. Go Premium"*

Try:

✅ *"You're using the trial version. Upgrade today"*

Also, consider adjusting your language to make the benefits of upgrading clearer. For example, instead of:

❌ *"This item is premium"*

Try:

✅ *"Subscribe to access unlimited illustrations like these"*

## Branding your add-ons for monetization

When building your checkout experience to monetize your add-ons, you can use the approved colors, gradients, and iconography to communicate when content or features in your add-on require purchase and when content or features are paid and unlocked.

### Best practices

Here are some guidelines for effectively communicating purchasing options and upgrades within your add-ons:

-   Use visual cues like the "plus" gradient badge to indicate that certain features require a purchase. The "plus" icon visually suggests that users can upgrade their experience.
-   Provide textual cues through tooltips to inform users about in-app purchase options. Consider using phrases like "add" alongside the plus badge to convey that users can access additional features or content by upgrading.
-   Use the "paid" green checkmark badge to signify when a feature or asset has been successfully added after purchase.
-   Use terms like "upgrade," "add," "Pro," and "Plus," for example:
    -   Add this [feature] by upgrading the add-on.
    -   Add more when you upgrade.
    -   Upgrade to Pro.
    -   Upgrade to [Add-on name] Plus.
- At the beginning of the upgrade flow, let users know that they will have to navigate to an external payment processor to complete their upgrade purchase, for example:
    -   "You'll need to pay to upgrade outside of Adobe."
-   Include a disclaimer in your checkout flow to remind users that upgrading the add-on does not change their access to Adobe Express Premium, for example:
    -   "This upgrade only applies to the [Add-on name] add-on and does not grant or remove access to Adobe Express Premium."

### Patterns to avoid

While our monetization best practices are recommendations for your add-on, implementing the following patterns to avoid them may result in a rejected submission.

-   🚫 Don't use any crown icons, colors, or gradients associated with Adobe Express Premium.
-   🚫 Don't use "Premium" for your add-on's upgrade experience.
-   🚫 Don't use a lock icon because it conflicts with the "lock layer" feature in Express. If you previously implemented this pattern, we recommend updating to the "plus badge" in your next submission.

###  Branding assets for monetization

#### Plus badge

Use the plus gradient icon below to indicate when content or features require purchase:

| Badge  | Size(px) | Download link |
|--------|----------|-------------:|
| <img src="../img/addon-plus-badge20.svg" width="20" height="20"/> | 20x20 | <a href="../img/addon-plus-badge20.svg" download="../img/addon-plus-badge20.svg">Download</a> |

#### Paid badge

Use the checkmark badge below to indicate when content or features are paid and unlocked:

| Badge  | Size(px) | Download link |
|--------|----------|-------------:|
| <img src="../img/addon-pro-badge20.svg" width="20" height="20"/> | 20x20 | <a href="../img/addon-pro-badge20.svg" download="../img/addon-pro-badge20.svg">Download</a> |

<InlineAlert slots="text" variant="info"/>

The most common size of badges used within Express panels is typically 20x20px, so we've included an easy download of that size specifically above. However, since it's an `.svg` icon, you could simply scale it to another size as needed.

#### General badge recommendations

- As a general rule, badges should be placed on the bottom right or right side of the paywalled content or feature.
- The badge size should typically be 18px or 20px, but can be adjusted depending on the size of the content it is paired with.
- We highly recommend adding a tooltip to let your users know what the badge indicates, i.e. *This content is available when you upgrade the add-on*.
- Using the "paid" badge is optional. The paid badge makes the most sense in situations where you want to highlight specific content is now unlocked, in particular "micro-transactions".
- If a user has paid for full access to an add-on through a one-time payment or subscription, then the "paid" badge is not really necessary.<br/><br/>

 | Sample badge usage  |      |       |
 |----------|------|-------------:|
 | <img src="../img/list-placement-example.png"/> | <img src="../img/avatar-placement-example.png"/>  | <img src="../img/grid-placement-example.png"/> |

<InlineAlert slots="text" variant="success"/>

For other examples of badge sizes and placement used in Adobe Express, check the **Templates** or **Media** panel for instance, where you'll see content marked with a crown icon used to denote Adobe Express Premium content.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: Submission and Review - Overview
description: This is the submission and review overview page
contributors:
  - https://github.com/hollyschinsky
---

# Distribution Overview

Congratulations! You've built a great add-on and you're ready to release it to the community.

To publish and share your add-on, it must first go through a review process. By reviewing every add-on, Adobe aims to help you get your add-ons ready for prime time and helps to ensures your users have great experiences with the add-ons they consume. Our goal is to balance providing you with the best possible developer experience during the review process, while also ensuring the approved add-ons offer a great user experience for our mutual customers.

<InlineAlert slots="text" variant="success"/>

This set of guides is meant to provide you with an idea of what types of information you will need for the submission process and how to best prepare for review. Working through the guides provided in this section will help you make sure you’ve accounted for all of our review requirements, so you can avoid having to fix things and resubmit before being published.

Check out this short video below on how to share and publish your add-on to help you get started more quickly. <br/><br/>

<div style="display: flex; justify-content: center;">
  <iframe width="560" height="315" src="https://www.youtube.com/embed/Xdu7TRSsU3I?si=kUcJ6EMnQeNVQa-X" title="Sharing and Publishing Your Add-on" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>

<!-- 

## Review Guides

- [Review Guidelines](review_guidelines.md)

## Distribution Guides
- [Submit for Private Distribution](../distribute/submit-private-dist.md)
- [Submit for Public Distribution](../distribute/submit-public-dist.md) -->

<!-- ## Submission Requirements

### Publisher profile

Your publisher profile contains information about you as a company or developer as a whole. Once you've submitted this information and it has been approved by Adobe, it will be shown for all add-ons and integrations you publish with Adobe.

Your publisher profile includes required details including:

1. Your publisher public name (often company name or, or your own name)

2. Your publisher marketing website (this website shows things you publish with Adobe and should be scoped to you as the publisher, not scoped to any single add-on or integration you submit)

3. A description of you, the publisher

4. Your logo (in `.jpg` or `.png` format with a size of 250x250 px)

<InlineAlert slots="text" variant="info"/>

**IMPORTANT:** You must complete and submit your publisher profile in order to submit your first add-on, however this is only a one-time thing (unless you decide you need to update it for your own reasons). **Note:** Any changes to your publisher profile will need to be submitted for approval again.
Frequently changing your publisher profile can confuse users and erode trust. Please be sure you've considered this before changing this information.

 -->

<!-- 
### Private Distribution Requirements
#### Assets:

1. **Icon**

    3 sizes required in `.jpg` or `.png` format:

    - Size 36x36px

### Public Distribution Requirements

#### Assets:

1. **Icons**

    3 sizes required in `.jpg` or `.png` format:

    - Size 36x36px
    - Size 64x64px
    - Size 144x144px
    
    <InlineAlert slots="text" variant="warning"/>
    
    All three sizes are mandatory.

2. **Screenshots**
    
    1-5 screenshots with dimensions of 1360x800px in `.jpg` or `.png` format. 
    
    <InlineAlert slots="text" variant="warning"/>
    
    At least one screenshot is mandatory.        

#### Metadata Requirements:

1. **Publisher Metadata**
    - Publisher Name
    - Publisher Description
    - Publisher Website
    - Publisher Logo
2. **Add-on Metadata**
    - Support Email
    - Help Url
    - Privacy Policy
    - License Agreement
    - Name
    - Description
    - Summary
    - Keywords
3. **Version Metadata**
    - Version release notes -->
# Add-on Listing Guide

### Listing Details

Your listing metadata provides Adobe and users with details about the add-on you are currently submitting. See the [add-on version details below](#add-on-version-details) for the metadata that is submitted for each add-on version.

The information you add in the following tabs will be made public to users via Adobe's Marketplace surfaces once your listing is published.

#### General Tab

- Public add-on name
- Subtitle
- Support email
- Help URL
- Description

#### Localizations Tab

Localized versions of:

- Public add-on name
- Subtitle
- Description

#### Media Tab

- 3 add-on icon sizes

#### Tags Tab

- Categories
- Custom Tags

#### Services Tab

- Privacy policy
- Terms of service
- Commerce: purchase method (paid or free)

### add-on Version Details

Here you will provide add-on level details for each add-on version submitted.

The information you add in the following tabs will be made public to users via Adobe's Marketplace surfaces once your version is published.

#### General Tab

- add-on package file (see the [section below](#add-on-package))
- If your add-on requires another application
- If your add-on requires a 3rd party service
- add-on UI supported languages
- Release notes

#### Localizations Tab

Localized versions of:

- Release notes

#### Media Tab

- Screenshots
- Videos

#### Add-on package

As part of your submission, you will upload your add-on package. Take the following steps to create your add-on package.

1. Compress your add-on files as a **.zip** file

   - Select all files within your add-on's parent folder. On both macOS and Windows you can right-click to compress:

     **macOS**:
     Right-click > Compress items

     **Windows**:
     Right-click > Send to > Compressed (zipped) folder

     **Note:** You should _not_ compress the add-on's parent folder. Instead, compress the contents of the parent folder. Failure to do so will likely cause a rejection when submitting.

#### Trader information

<InlineAlert variant="info" slots="text" />

This information will be displayed to only users in the European Union (EU) region in accordance with the [European Union Digital Services Act](https://eur-lex.europa.eu/legal-content/EN/ALL/?uri=CELEX:32022R2065) trader requirements.

- Email
- Telephone
- Address
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: Create a Private Distribution Link
description: A guide to creating a private distribution link. 
contributors:
  - https://github.com/hollyschinsky
  - https://github.com/undavide
---

# Create a Private Distribution Link

## Overview

You can choose to create a private link to share your add-on with others to use or test by following the instructions outlined in this section.

## Prepare your add-on package

In the process of creating a private link, you will be required to upload a zip of your add-on package. The CLI contains a handy script to help with this step. Before you proceed, open your terminal and navigate to the root of your add-on project, then run the following command.

```bash
npm run package
```

The result will be a distributable zip of your add-on package with the name `dist.zip`, and can be uploaded in step 3 below. This add-on package contains the **production-ready built content** in the *root* of the zip file, similar to what's built into the `/dist` folder.

## Step 1: Create a new Add-on Listing

In order to get a private distribution link, you will need to create a new add-on listing first; provided that you've enabled Add-on Development in your user's settings as described [here](../getting_started/quickstart.md#step-3-enable-add-on-development-mode-first-time-only), you can do so in two ways, which will invoke the same in-app distribution experience.

1. From the Adobe Express home page, click the Add-ons link in the left-hand navigation.

![Add-ons from home page](./img/add-ons-from-home-v2.png)

2. While loading a local add-on, click the **Manage add-ons** link in the Add-on Testing section.

![Manage link in launchpad](./img/manage-v2.png)

In case you haven't created any listings for your add-ons yet, you will see the following.

![First add-on submission modal](./img/distrib-first-v2.png)

If you have existing listings, instead, your first screen will display them, alongside the possibility of adding a new one.

![First screen of submission modal with existing listings](./img/distrib-existing-v2.png)

Select **Create new** from either, and type the add-on name in the following modal dialog (25 characters max). Your add-on name will be validated when you tab out (or the field loses focus) before you will be allowed to move to the next step. You will know that it's verified by a green checkmark shown, or receive an error that it exists, and you need to choose another.

![Add-on name modal](./img/create-new-v2.png)

## Step 2: Add-on Listing Settings

Your add-on container will be created and a settings panel like the one shown below will be presented. Please note the unique subdomain URL from where your add-on will be hosted, and a button to delete the listing if needed.

![](./img/subdomain-v2.png)

## Step 3: Create a new private link

Navigate to the **Private link** tab, and click the **Create private link** button to proceed.

![Create Private link](./img/create-private-link-v2.png)

## Step 4: Upload your add-on package

The next step is to upload your package. Either drag and drop the add-on package `.zip` file, or click the **browse** link to select the file from your computer's filesystem.

<InlineAlert slots="text" variant="info"/>

In case you missed it, the [top section on preparing your add-on package](#prepare-your-add-on-package) can be used to help you create the zip file needed for this step.

![Empty upload modal](./img/create-private-link-package-v2.png)

The package will go through a verification process which may take a few seconds, so please be patient. In case you receive an error, please review the following warning notes.

<InlineAlert slots="text1, text2, text3, text4" variant="warning"/>

**1.** If you receive a `MANIFEST_NOT_FOUND_ERROR`, instead of zipping the folder containing the add-on files, please zip only the contents. For example, manifest file would be at the **root** level of the extracted package.

**2.** Your add-on package file size must not exceed 50 MB.

**3.** In places where you are referring to paths, please ensure you are only using relative paths.

**4.** Hidden files should not be present in your package zip. You can use this command on MAC to zip your add-on and to ensure unnecessary files are not included:   `zip -r your_addon_name.zip . -x '**/.*' -x '**/__MACOSX' -x '*.DS_Store'`. The `package` script [described earlier](#prepare-your-add-on-package) takes care of this for you.

## Step 5: Enter add-on details

If the `zip` validation is successful, you will see a green checkmark next to the **Add-on package verified** text, and you can add some Release Notes (1000 characters max) and a 144 x 144px icon.

![Verified](./img/create-private-link-details-v2.png)

<!-- <InlineAlert slots="text" variant="success"/>

The number of characters allowed for any given field is shown above it throughout the distribution experience (for instance, the name field allows a max of 25 characters). The number will automatically update with the remaining amount as you're typing into it. -->

Once you've entered the required fields, the **Save and create private link** button will be enabled.

<InlineAlert slots="text" variant="warning"/>

The button will only be enabled if you have entered all of the required data. Also, upon clicking, it may take a moment to send the package and details to the backend server to generate the link, so please be patient.

![Submit data to create private link](./img/save-create-private-link-v2.png)

When the process is finished, you'll be greeted by the following popup. Click the **Copy link and close** to copy your private link for sharing.

![Successfully created link](./img/create-private-link-success-v2.png)

## Post-Submission details and insights

You can choose to revisit your submission details now if you want to copy, delete, update your link, or choose to create a public listing from it. It's possible also at a later time: in case, choose **Manage add-ons** from the add-on launchpad again, and then select your add-on submission. You will see the details and options available as shown in the screenshot below.

![private listing details](./img/create-private-link-review-v2.png)

If you select the **Insights** tab, you'll be able to get analytics for your add-on, via the **Download** buttons.

![listing insights](./img/add-on-insights-v2.png)

The insights come as `.csv` files named like your add-on, and appended with `_public` or `_private` depending on the listing type (e.g., `AFineAddOn_private.csv`). The insights data currently includes the number of installs, uninstalls and invocations of your add-on per week. A sample is shown below for reference:

![sample insights](./img/sample-insights.png)
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
  - DSA
title: Public add-on distribution
description: A guide to public distribution of your add-on. 
contributors:
  - https://github.com/hollyschinsky
  - https://github.com/undavide
  - https://github.com/nimithajalal
---

# Public add-on Distribution

## Overview

This guide is provided to help ensure your add-on distribution process goes as smoothly as possible. We've provided a list of all of the things you can prepare in advance, as well as the steps to follow to actually submit your add-on for public distribution. Please note that public distribution is subject to a quality review by our team according to our [Guidelines](./guidelines/index.md).

## Preparing for Submission

This section outlines everything you'll need to be prepared for submitting your add-on for public distribution.

### 1. Prepare your metadata

**\* Indicates Required**

| Name                    | Character Length  | Description   |
| -------------:          | ------------------| -----------:  |
| **\* Add-on name**      | 25                | A unique name for your add-on.|
| **\* Summary**               | 50                | A short description of what your add-on does.|
| **\* Full Description**      | 1000              | Full context and description of your add-on and its features |
| **\* Help URL**              | 1000              | URL for your users to get help (ie: https://www.example.com/)  |
| **\* Support email address** | 1000              | An email address that users of your add-on can contact for support |
| **\*Trader information**     | NA                | Provide the trader information as per the [listing guidelines](./guidelines/general/listing.md#trader-details) in the publisher profile if you want to make your addons available in the EU |
| **Privacy Notice**          | 1000              | URL of your privacy notice (ie: https://www.example.com/) |
| **End User License Agreement(EULA)**| 1000      | End User License Agreement URL (ie: https://www.example.com/) |
| **Keywords**                | 100              | Keywords to help users find your add-on (comma-separated) |
| **Release notes**       | 1000  | Provide information specific to this version of the add-on |

### 2. Prepare your assets

| Type           | Format      | Description   |
| -------------: | ------------| -----------:  |
| * 144x144 icon         | `.jpg/png`  | a 144x144 sized icon representing your add-on |
| * Screenshot           | `.jpg/png`  | a 1360x800 sized screenshot to show users how to use your add-on |
|   Additional screenshots | `.jpg/png` | 4 more optional 1360x800 sized screenshots for your add-on |
| ** Publisher logo       | `.jpg/png`  | 250x250 sized logo to represent you or your company |

<InlineAlert slots="text" variant="info"/>

A **publisher logo** is only required the first time you submit for distribution, and if you've never created a publisher profile.

### 3. Prepare your add-on package

The CLI contains a handy script to help with this step. Before you proceed, open your terminal and navigate to the root of your add-on project, then run the following command.

```bash
npm run package
```

The result will be a distributable zip of your add-on package with the name `dist.zip`, and can be uploaded in step 3 below. This add-on package contains the **production-ready built content** in the *root* of the zip file, similar to what's built into the `/dist` folder.

### 4. Carefully [review our set of guidelines](./guidelines/index.md)

## Submission Steps

This set of steps can be followed when you have everything prepared, have diligently reviewed the guidelines, and are ready to submit your add-on for review via the Adobe Express in-app distribution experience.

### Step 1: Create a new Add-on Listing

To distribute your add-on, you must create an add-on listing.

<InlineAlert slots="text" variant="info"/>

If you have already performed the listing creation steps, e.g. to create a Private Link as outlined here, feel free to skip to
[Step 3](#step-3-create-a-new-public-listing).

Provided that you've enabled Add-on Development in your user's settings as described [here](../getting_started/quickstart.md#step-3-enable-add-on-development-mode-first-time-only), you can do so in two ways, which will invoke the same in-app distribution experience.

**1.** From the Adobe Express home page, click the Add-ons link in the left-hand navigation.

![Add-ons from home page](./img/add-ons-from-home-v2.png)

**2.** While loading a local add-on, click the **Manage add-ons** link in the Add-on Testing section.

![Manage link in launchpad](./img/manage-v2.png)

In case you haven't created any listings for your add-ons yet, you will see the following.

![First add-on submission modal](./img/distrib-first-v2.png)

If you have existing listings, instead, your first screen will display them, alongside the possibility of adding a new one.

![First screen of submission modal with existing listings](./img/distrib-existing-v2.png)

Select **Create new** from either, and type the add-on name in the following modal dialog (25 characters max). Your add-on name will be validated when you tab out (or the field loses focus) before you will be allowed to move to the next step. You will know that it's verified by a green checkmark shown, or receive an error that it exists, and you need to choose another.

![Add-on name modal](./img/create-new-v2.png)

### Step 2: Add-on Listing Settings

Your add-on container will be created and a settings panel like the one shown below will be presented. Please note the unique subdomain URL from where your add-on will be hosted, and a button to delete the listing if needed.

![](./img/subdomain-v2.png)

### Step 3: Create a new public listing

Navigate to the **Public listing** tab, and click the **Create public listing** button to proceed.

![Public listing creation](./img/create-public-listing-v2.png)

### Step 4: Enter listing details

The **"Create a public listing"** page contains a number of form inputs, grouped into logical sections that start as blank.

![Public listing blank](./img/public-listing-blank-v2.png)

Fill the details with the requested information. The **Add-on name** must be unique, 25 characters max. It will be validated when you tab out (or the field loses focus) before you can move to the next step. You will know that it's verified by a green checkmark, or you'll receive an error, in which case you'll need to choose another.

The **icon** must be of the size, 144 px. Once you upload an icon, it will be auto-resized into **Minimized add-on module icon(36 px)**, **Panel header icon (64 px)** and **Launchpad icon (144 px)**.

![Public listing blank](./img/public-listing-icon-resize.png)

All the other **textual fields** have a character count that update with the remaining amount as you're typing into them. Please ensure your URLs and email addresses are properly formed to avoid unnecessary errors.

<InlineAlert slots="text" variant="success"/>

The `*` indicates required fields. Note that you can skip entering these required fields if you are only planning to save a draft with your current edit, though you will not be able to submit it until they are completed.

Please note the dropdown checklist below the **"Jump to"** label, in the top-left corner: you can use it to scroll to the relevant part of the document—complete sections are marked in green. Also note a Progress bar, indicating how far you are in the listing compilation.

![Public listing details jump to](./img/public-listing-jump-to-v2.png)

### Step 5: Upload screenshots

In the next section, you should upload 1-5 screenshots to show off your add-on and what it's all about. Please note, at least one screenshot is required.

<InlineAlert slots="text" variant="warning"/>

Sometimes it may take a moment to upload the images to the back-end server, please be patient.

### Step 6: Upload your add-on package

It's time to upload your package. Either drag and drop the add-on package `.zip` file, or click the **browse** link to select the file from your computer's filesystem.

<InlineAlert slots="text" variant="info"/>

In case you missed it, the [top section on preparing your add-on package](#3-prepare-your-add-on-package) can be used to help you create the zip file needed for this step.

The package will go through a verification process which may take a few seconds, so please be patient. In case you receive an error, please review the following warning notes.

<InlineAlert slots="text1, text2, text3, text4" variant="warning"/>

**1.** If you receive a `MANIFEST_NOT_FOUND_ERROR`, instead of zipping the folder containing the add-on files, please zip only the contents. For example, manifest file would be at the **root** level of the extracted package.

**2.** Your add-on package file size must not exceed 50 MB.

**3.** In places where you are referring to paths, please ensure you are only using relative paths.

**4.** Hidden files should not be present in your package zip. You can use this command on MAC to zip your add-on and to ensure unnecessary files are not included:   `zip -r your_addon_name.zip . -x '**/.*' -x '**/__MACOSX' -x '*.DS_Store'`. The `package` script [described earlier](#3-prepare-your-add-on-package) takes care of this for you.

If the `zip` validation is successful, you will see a green checkmark next to the **Add-on package verified** text; you can then add some Release Notes (1000 characters max) and check the add-on's supported languages.

### Step 7: Enter the AI usage details

The rise of Generative AI offers significant benefits for add-ons and streamlines content creation and workflows. Adobe encourages user choice regarding add-ons using Generative AI, but transparency is paramount. Your AI-powered add-on must not generate illegal content, and it must be clear and transparent about how generative AI is used in your add-on.

In this section, you'll have to answer a variety of questions, depending on the type of AI-based content your add-on generates, the input it accepts, whether you test the output, etc. Carefully review our [AI usage guidelines](./guidelines/genai/index.md) to get the latest information on Adobe’s requirements and recommendations to try add-ons that employ Generative AI technology.

### Step 8: Enter the monetization details

The **Monetization details** section allows developers to declare the payment option they support for their add-on. A selection is required for any new add-on submitted, and existing add-ons can be updated to include or change the selection. The monetization details entered can be seen in the preview of the listing (on the right) before submission, and in the add-on details once published.

![Monetization details](./img/public-listing-monetization-v2.png)

Developers can choose from various payment options, including **free**, **one-time payments**, **recurring subscriptions**, **micro-transactions**, and more. Select the monetization options that suit your preferences best. Use the [examples](./guidelines/monetization.md#requirements-for-monetizing-your-add-ons) outlined in the guidelines for monetizing add-ons to help you make informed decisions about which options to choose.

- The *Other* option is provided for developers to choose when their current setup does not fit the provided options.
- The final *additional details* text area allows developers to provide additional payment terms like *"7 day free trial"* or *"$9.99/month"* and is optional for all payment choices except *Other*. We encourage the use of this field to clearly state any specific payment details.

Do check in the live preview how the listing will appear to users. Depending on the payment selection, different details will automatically be displayed in the add-on listing.

If the payment choice selected is not free, an **Upgrade available** badge will be displayed in the details along with specific default text describing the choice selected (ie: "*...for a one-time purchase*", "*...with a recurring subscription*", "*...purchase assets or features individually or in packages*"), and **Checkout is handled by the developer outside of Adobe Express**—as shown in the previous screenshot.

Any additional custom details entered by the developer are then shown below the default checkout message, as well as a timestamp indicating when the listing was last updated.

In the case of the **free** payment selection, the following text simply be shown: "This add-on does not require any payment".

<!-- If you wish to explore alternative monetization methods for your add-on, you may do so by selecting **Other** and providing relevant details in the **Additional Details** section. This information will be visible to Adobe Express users within the add-on details. We recommend clearly stating the pricing for add-on upgrades, any recurring fees, and any additional costs that users may encounter. -->

Carefully review our [monetization guidelines](./guidelines/monetization.md) to get the latest information on Adobe’s requirements and recommendations for monetizing your add-ons.

### Step 9: Create a publisher profile

<InlineAlert slots="text" variant="info"/>
You will only see this step the first time you submit an add-on and if you've never created a publisher profile before to this submission.

- Fill your publisher profile details.
- Upload a 250x250 logo.
- Add your trader details: In accordance with the European Union Digital Services Act trader requirements, developers who wish to distribute their listings in the EU must provide additional information in their publisher profile. [Learn more](./guidelines/general/listing.md#trader-details) about adding trader details.

#### Edit publisher profile

The existing developers can now edit their publisher profile to add trader details.

Choose **Yes** if you wish to make your add-ons available for users in the EU.
  
<InlineAlert variant="warning" slots="text1, text2, text3" />

**Are you an existing developer?**

You must provide trader details by February 16, 2025, to keep your add-on visible and available in Adobe Express for users in the European Union as of February 17, 2025. This trader information will be displayed publicly on your listing detail pages when viewed from EU countries.

[Add trader details now.](https://new.express.adobe.com/add-ons?mode=submission)

![Publisher Profile](./img/pub-profile2.png)

### Step 10: Final submission

- Enter your **Notes to reviewer**
  - Add there any relevant information for the vetting team, including coupon codes that may allow them to test premium features for free. Carefully review all the information entered.
- Click the **Submit for review** button in the top-right corner.

![Submitting the listing](./img/public-listing-submission-v2.png)

<InlineAlert slots="text" variant="warning"/>

The **Submit for review** button will only be enabled if you have entered all of the required data.

In case there are any errors, a message will be displayed at the bottom of the page. Follow the instructions to fix them, and try submitting again.

Eventually, the submission will be successful. Congratulations!

Click **View submission details** to see the details of your add-on submission.

You can choose to revisit your submission details later if you need to update it, or if you want to download insights for your add-on. To do so, choose **Manage add-ons** from the add-on launchpad again, and then select your add-on listing.

<InlineAlert variant="warning" slots="header, text1, text2" />

Add-on visbility for EU users

If an EU user has a deep link to your add-on, and you are not compliant with the [European Union Digital Services Act](https://eur-lex.europa.eu/legal-content/EN/ALL/?uri=CELEX:32022R2065) trader requirements, they will not be able to install the add-on. However, if they have already installed it, they will still be able to use it. In both cases, they will see a banner with the following message:

*This listing is not currently available in the EU. This developer has not submitted the trader information required by the EU Digital Services Act.*

## Post-Submission details and insights

When the add-on will be published, you will see the details, as shown in the screenshot below.

![public listing details](./img/public-listing-published-v2.png)

If you select the **Insights** tab, you'll be able to get analytics for your add-on, via the **Download** buttons.

![listing insights](./img/add-on-insights-v2.png)

The insights come as `.csv` files named like your add-on, and appended with `_public` or `_private` depending on the listing type (e.g., `AFineAddOn_private.csv`). The insights data currently includes the number of installs, uninstalls and invocations of your add-on per week. A sample is shown below for reference:

![sample insights](./img/sample-insights.png)
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: Common rejection causes
description: A guide to Common add-on's rejection causes
contributors:
  - https://github.com/undavide
---

# Common Rejection Causes and How To Avoid Them

## 📋 Overview

When you submit an add-on for distribution, the review team *thoroughly* examines it to ensure it meets the [guidelines](./guidelines/index.md) and is safe for public distribution. If something goes wrong, you will receive an email with the reasons that led to a rejection. You shouldn't be discouraged, though! Usually, the fixes are relatively straightforward, and the detailed feedback from the reviewers is an opportunity to improve and learn.

That said, being rejected is annoying and, most importantly, time-consuming, as multiple re-submissions will impact the time it takes to get your add-on published. To help you avoid it, we've compiled a list of the most common reasons for review failures and how to address them.

## 🔧 Functional issues

As trivial as it may sound, the add-on not working as expected is the **most common cause** of trouble. This can be anything from a simple failure to the inability to log in. Here are some of the most common functional issues the reviewers have reported and our suggestions to prevent them.

### Broken features

Problems can be directly related to the **add-on's core functionality**, e.g., failures in exporting from and importing assets into the document or performing server-side processing. Sometimes, bugs are sneaky and only appear under specific conditions, which our reviewers have proved *exceptionally talented* in finding—just so you know. Test your add-on thoroughly and make sure it works in all scenarios, edge cases included.

![](./img/rejections-functional-issues.png)

### Minor bugs

The reviewers will also reject your add-on if they find less critical problems that still **affect the user experience**. Issues could vary from missing event handlers to 404 links and broken icons. Do your best to catch them all before submitting your add-on.

![](./img/rejections-404-error.png)

### Authentication problems

In case your product requires users to log in, make sure the **authentication workflow is operating properly**, and don't forget to *always* add a logout option. If present, reviewers should also be provided with working **credentials to test premium features**, a key requirement for add-ons that offer paid services.

![](./img/rejections-authentication-failed.png)

### Browser compatibility

Adobe Express [officially supports](https://helpx.adobe.com/express/system-requirements.html#system-requirements-web) the four most popular browsers: **Chrome, Safari, Edge, and Firefox**. Your add-on must be tested and work seamlessly across all of them. If any problems discussed so far are found in even one of these browsers, the reviewers are bound to reject it.

![](./img/rejections-browser-compatibility.png)

## 📐 UI/UX Issues

Both the User Interface and Experience—i.e., how information is presented to users and how they interact with it—are crucial elements for the success of your products. Here are some common pitfalls that can prevent your add-on from being approved.

### Navigation problems

The UI should always provide an intuitive and **functional way to navigate the add-on's screens**. It should also offer a method to return to the previous screen or home page, especially if a PDF or webpage is opened in the iframe and overrides its entire content. If users can't find a clear path to follow and get stuck, the reviewers will throw the ball back in your court and ask you to revise your code.

![](./img/rejections-navigation-problems.png)

### Error handling

Every **user interaction should always return clear feedback**. For instance, progress indicators or text notices should be displayed when the add-on runs a process in the background to signal that it is actually doing something and is not idle or frozen. Input fields should have proper validation to avoid errors with out-of-bounds values in your routines, and displayed errors should be informative and actionable. Additional information should be provided as tooltips or text to clarify why elements are disabled or actions are unavailable. It's relatively common to forget about these details, but they are a typical cause of review failures; make sure to remember them.

![](./img/rejections-error-feedback.png)

## 📝 Recent changes to review criteria

Due to changes in the testing and reviewing processes, some issues that used to cause rejections aren't considered blocking anymore. Please find below some of the most recent ones.

### Relaxed UI Requirements

Using the [Spectrum Design System](../design/implementation_guide.md#spectrum-design-system) is **no longer mandatory**, provided that the add-on's UI follows the best practices outlined in the [UX Guidelines](../design/ux_guidelines/introduction.md) and is well-crafted. Spectrum Web Components and the Spectrum Express theme are still the recommended options, as they reliably provide a native look and feel. Mind you, malfunctioning or poorly designed UIs will always be rejected regardless of the design system used.

### COEP issues

The reviewing team **no longer tests** for [COEP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) (Cross-Origin Embedder Policy), which used to cause, e.g., broken images. [CORS](../develop/context.md#cors) (Cross-Origin Resource Sharing) policies are still enforced, though, so make sure your add-on doesn't break due to them.
# Our Review Process

## Overview

We’ve created the Adobe Express Add-ons marketplace so that Adobe users can benefit from amazing ideas from our developer community - including you.

Whether you’re creating new features or speeding up user workflows, we want you to use your imagination.

But we want every add-on to perform as thorough as possible, which is why each submission goes through a thorough review process before being accepted.

## Review Criteria

Our marketplace reviewers will assess your submission based on a variety of factors, including:

- Branding
- Performance
- Accessibility
- Harmful or unacceptable content
- User Experience
- Transparency
- Presence of bugs or harmful code
- Compatibility with operating systems, browsers, devices and other add-ons

<InlineAlert slots="text" variant="info"/>

**We aim to review your add-on within 10 business days of submission, and will let you know if it is accepted, or if any changes need to be made.**

## Submission Checklist

To make sure your review process goes smoothly, check off the tasks in this list before submitting.

If you have any questions, feel free to contact us at [ccintrev@adobe.com](mailto:ccintrev@adobe.com) or reach out on our [Adobe Express Add-on Developer’s Discord channel](http://discord.gg/nc3QDyFeb4).

### 1. Make sure you’ve included all required files in your add-on submission, as per the [Creating a public listing documentation](../public-dist.md), including:

- Files
- Assets
- Release notes
- Testing information

### 2. Provide accurate and up-to-date information, including:

- Add-on name
- Version
- Author
- Contact information
- Trader infromation in the publisher profile if you wish to distribute your add-ons in the EU region.

### 3. Ensure your add-on meets legal and licensing requirements, including:

- Attribution
- Copyright
- Intellectual property rights
- Share testing credentials with the review team so they can validate functionality

### 4. Make sure the add-on meets our [Developer Brand Guidelines](https://developer.adobe.com/express/embed-sdk/docs/assets/34359598a6bd85d69f1f09839ec43e12/Adobe_Express_Partner_Program_brand_guide.pdf)

### 5. Ensure that you have read and followed all Adobe guidelines relating to your add-on, including:

- Our [Developer Brand Guidelines](../guidelines/brand_guidelines.md)
- Our [Monetization Guidelines](../guidelines/monetization.md) (if you are monetizing your add-on)
- Our [Generative AI Guidelines](../guidelines/genai/) (if you are using Generative AI)
# Submission Checklist

To make sure your review process goes smoothly, check off the tasks in this list before submitting.

If you have any questions, feel free to contact us at [ccintrev@adobe.com](mailto:ccintrev@adobe.com) or on our [Adobe Express Add-on Developer’s Discord channel](http://discord.gg/nc3QDyFeb4).

## Make sure you’ve included all required files in your add-on submission, as per the [submission guidelines](../public-dist.md#preparing-for-submission), including:

- Files
- Assets
- Release notes
- Testing information

## Provide accurate and up-to-date information, including:

- Add-on name
- Version
- Author
- Contact information
- Trader infromation in the publisher profile if you wish to distribute your add-ons in the EU region.
  - Business D-U-N-S number [`optional`]

## Ensure your add-on meets legal and licensing requirements, including:

- Attribution
- Copyright
- Intellectual property rights
- Share testing credentials with the review team so they can validate functionality

## Make sure the add-on meets the [Developer Brand Guidelines](https://developer.adobe.com/express/embed-sdk/docs/assets/34359598a6bd85d69f1f09839ec43e12/Adobe_Express_Partner_Program_brand_guide.pdf)

## Check your add-on and resources to make sure it is NOT described as a “plugin” anywhere

## Ensure that you have read and followed all Adobe guidelines relating to your add-on, including:

- [Developer Brand Guidelines](../guidelines/brand_guidelines.md)
- Our [Monetization Guidelines](../guidelines/monetization.md) (if you are monetizing your add-on)
- Our [Generative AI Guidelines](../guidelines/genai/) (if you are using Generative AI)
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
  - DSA
  - Adobe DSA requirements
  - Compliance
title: FAQ
description: A list of frequently asked questions and answers.
contributors:
  - https://github.com/hollyschinsky
  - https://github.com/undavide
  - https://github.com/nimithajalal
---

# Frequently Asked Questions

## Questions

- [How do I run on a different port than the default (ie: 8080 for example)?](#how-do-i-run-on-a-different-port-than-the-default-ie-8080-for-example)
- [Is `yarn` supported with the CLI, or only `npm`?](#is-yarn-supported-with-the-cli-or-only-npm)
- [How do I save the state of my add-on?](#how-do-i-save-the-state-of-my-add-on)
- [How do I use top level `await` while using webpack?](#how-do-i-use-top-level-await-while-using-webpack)
- [How do I setup webpack to copy new files or folders into `dist`?](#how-do-i-setup-webpack-to-copy-new-files-or-folders-into-dist)
- [My form submission doesn't work and the devtools console shows the error: "Blocked form submission to " " because the form's frame is sandboxed and the 'allow-forms' permission is not set." What's wrong?"](#my-form-submission-doesnt-work-and-the-devtools-console-shows-the-error-blocked-form-submission-to---because-the-forms-frame-is-sandboxed-and-the-allow-forms-permission-is-not-set-whats-wrong)
- [How do I enable CORS for a service that blocks my add-on requests due to the origin?](#how-do-i-enable-cors-for-a-service-that-blocks-my-add-on-requests-due-to-the-origin)
- [How do I prevent my iframe content from being blocked due to cross-origin issues?](#how-do-i-prevent-my-iframe-content-from-being-blocked-due-to-cross-origin-issues)
- [The `Window.showOpenFilePicker()` API is not working from within my add-on, why not?](#the-windowshowopenfilepicker-api-is-not-working-from-within-my-add-on-why-not)
- [I’m not able to load the add-on in the browser anymore. When I click on "Connect”, I get an error `ERR_CERT_AUTHORITY_INVALID`.](#im-not-able-to-load-the-add-on-in-the-browser-anymore-when-i-click-on-connect-i-get-an-error-err_cert_authority_invalid)
- [I receive this error when trying to run my add-on: `Error: EISDIR: illegal operation on a directory`.](#i-receive-this-error-when-trying-to-run-my-add-on-error-eisdir-illegal-operation-on-a-directory)
- [I receive a `MANIFEST_NOT_FOUND_ERROR` during the package verification when trying to upload my plugin package for distribution.](#i-receive-a-manifest_not_found_error-during-the-package-verification-when-trying-to-upload-my-plugin-package-for-distribution)
- [How can I monetize my add-on?](#how-can-i-monetize-my-add-on)
- [What does it mean when an API is considered **experimental**?](#what-does-it-mean-when-an-api-is-considered-experimental)
- [What are the supported mime types/file formats for exported content?](#what-are-the-supported-mime-typesfile-formats-for-exported-content)
- [What are the supported file formats for imported content in Adobe Express?](#what-are-the-supported-file-formats-for-imported-content-in-adobe-express)
- [Are animated GIF's supported when importing or dragging content to the document?](#are-animated-gifs-supported-when-importing-or-dragging-content-to-the-document)
- [Why do I receive a "No 'Access-Control-Allow-Origin' header is present on the requested resource" error?](#why-do-i-receive-a-no-access-control-allow-origin-header-is-present-on-the-requested-resource-error)
- [Is `SharedArrayBuffer` supported?](#is-sharedarraybuffer-supported)
- [Which browsers and operating systems are currently supported?](#which-browsers-and-operating-systems-are-currently-supported)
- [How does Adobe use my add-on’s data?](#how-does-adobe-use-my-add-ons-data)
- [Where can I request new add-on features or suggest ideas?](#where-can-i-request-new-add-on-features-or-suggest-ideas)
- [Why does the CLI return the error: "Login failed. Please try again.", though I didn't have a chance to login because the browser never opened?](#why-does-the-cli-return-the-error-login-failed-please-try-again-though-i-didnt-have-a-chance-to-login-because-the-browser-never-opened)
- [What mime type is returned from a PDF that was exported with the `createRenditions` method?](#what-mime-type-is-returned-from-a-pdf-that-was-exported-with-the-createrenditions-method)
- [The latest version of the CLI is not automatically installing when I run the `npx` command to create a new add-on.](#the-latest-version-of-the-cli-is-not-automatically-installing-when-i-run-the-npx-command-to-create-a-new-add-on)
- [I'm trying to use a newly released feature, but it seems to be unavailable?](#im-trying-to-use-a-newly-released-feature-but-it-seems-to-be-unavailable)
- [Why is my add-on not visible in the EU region?](#why-is-my-add-on-not-visible-in-the-eu-region)
- [How can I update my trader details in the publisher profile after submission?](#how-can-i-update-my-trader-details-in-the-publisher-profile-after-submission)
- [What happens if an EU user has a deep link to my add-on and I am not compliant with the European Union Digital Services Act (DSA) trader requirements?](#what-happens-if-an-eu-user-has-a-deep-link-to-my-add-on-and-i-am-not-compliant-with-the-european-union-digital-services-act-dsa-trader-requirements)
- [Can an EU user still use my add-on if they have already installed it, but I am not compliant with the DSA trader requirements?](#can-an-eu-user-still-use-my-add-on-if-they-have-already-installed-it-but-i-am-not-compliant-with-the-dsa-trader-requirements)
- [Why is the CLI failing with an Invalid URL error when creating a new add-on on Windows?](#why-is-the-cli-failing-with-an-invalid-url-error-when-creating-a-new-add-on-on-windows)

## Answers

### How do I run on a different port than the default (ie: 8080 for example)?

Use the following syntax:

```bash
npm run start -- --port 8080
```

### Is `yarn` supported with the CLI, or only `npm`?

We recommend using `npm` for running the CLI scripts. Note that while there might be workarounds to get `yarn` working, we do not recommend it, or support any issues that may arise using `yarn`.

### How do I save the state of my add-on?

The add-on's state is reset quite frequently (changing panels, changing viewport widths etc), so one may want to save state to [ClientStorage](../references/addonsdk/instance-clientStorage.md) and use that to restore state when the add-on loads. For example, if the user has to navigate into a deep folder hierarchy, they may not want to repeat that again just because they clicked the media panel to add a shape. Or if they are editing a form (e.g., an AI prompt), they may not want to lose that content when they navigated to another panel for a moment. When it makes sense to store a lot of UI state (and when it doesn't) is highly dependent upon the add-on's use case.

### How do I use top level `await` while using webpack?

Set `experiments: { topLevelAwait: true}` in the webpack config file (otherwise you'll get a build error).

### How do I setup webpack to copy new files or folders into `dist`?

If you add any folders, (like images for example), to your `src`, you can update the `webpack.config.js` `CopyWebpackPlugin` section within to ensure those new resources added are copied into the `dist` folder. For instance, in the following, the 3rd line was added to ensure any `.jpg` files in the `src/images` folder get copied over:

```js
new CopyWebpackPlugin({
  patterns: [
    { from: "src/*.json", to: "[name][ext]" },
    { from: "src/*.png", to: "[name][ext]" },
    { from: "src/images/*.jpg", to: "images/[name][ext]" },
  ],
});
```

### My form submission doesn't work and the devtools console shows the error: "Blocked form submission to " " because the form's frame is sandboxed and the 'allow-forms' permission is not set." What's wrong?"

You can call `preventDefault` on the submit event to prevent the browser from trying to complete the full form submission process and avoid this error, such as:

```js
<form
  onSubmit={(evt) => {
    evt.preventDefault();
  }}
/>
```

**NOTE:** If the above does not work for you, you can also handle this by adding click handler to the submit button itself instead, and in that call `event.preventDefault` on the event, such as:

```javascript
<form onSubmit={(e) => e.preventDefault()}>
  <input
    type="submit"
    value="Submit"
    onClick={(e) => e.preventDefault()}
  />
</form>
```

### How do I enable CORS for a service that blocks my add-on requests due to the origin?

To help enable a smoother experience for developers dealing with CORS, we provide each add-on with a unique [subdomain](../guides/develop/context.md#subdomain) which can be supplied in the list of [allowed origins](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin) that can make requests to a given service. See the section on [CORS](../guides/develop/context.md#cors) for more details on determining your unique subdomain and using it to enable CORS.

### How do I prevent my iframe content from being blocked due to cross-origin issues?

If your iframe is being blocked by the browser, it's likely due to CORS issues. To resolve this, you need to set the appropriate HTTP headers on the server that hosts the content being loaded within the iframe. Specifically, you need to set the [`Cross-Origin-Embedder-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) header to `require-corp`.

### The `Window.showOpenFilePicker()` API is not working from within my add-on, why not?

You can open the file picker using the `input` element with a `type` set to `file` to get around this.

### I’m not able to load the add-on in the browser anymore. When I click on "Connect”, I get an error `ERR_CERT_AUTHORITY_INVALID`.

This usually indicates an issue with invalid SSL credentials. Locate the `devcert` folder which can be found at `/Users/{your_username}/Library/Application\ Support/devcert` on MAC or `C:\Users\{your_username}\AppData\Local\`, delete it, and create an add-on again. You should get the option to create an SSL certificate again when you create the new add-on, which should resolve your problem.

### I receive this error when trying to run my add-on: `Error: EISDIR: illegal operation on a directory`.

This usually indicates you do not have SSL configured correctly. You can fix it by clearing the configurations from the configuration file.

- In Windows, you can locate this file at: `C:\Users\{your_username}\AppData\Local\Adobe\CCWebAddOn\add-on-preferences.json`.

- On MAC, you can locate this file at: `/Users/{user}/Library/Application Support/Adobe/CCWebAddOn\add-on-preferences.json`

Once you find config file, delete the two properties defined for `sslCertPath` and `sslKeyPath` there. After they've been deleted, you can run the commands to create a new add-on where you will be prompted to set up SSL again and then be sure to specify the correct paths to your certificate and key file.

### I receive a `MANIFEST_NOT_FOUND_ERROR` during the package verification when trying to upload my plugin package for distribution.

Instead of zipping the folder containing the add-on files, please zip only the contents. In other words, manifest file should be at **root** level of the extracted package.

### How can I monetize my add-on?

At this time, the only way to monetize is by using a third party provider, and ensuring you choose one that provides safety measures, security and proper payment processing. Some options you may want to consider include **Gumroad**, **Stripe**, **Paddle** and **FastSpring**. Find out more about how you can communicate your monetization details to users in our [monetization guidelines](../guides/distribute/guidelines/monetization.md#branding-your-add-ons-for-monetization).

### What does it mean when an API is considered **experimental**?

Experimental APIs are those which have not been declared stable yet, and to try them, first need to set the `experimentalApis` flag to `true` in the [`requirements`](../references/manifest/index.md#requirements) section of the [`manifest.json`](../references/manifest/index.md). The `experimentalApis` flag is **only allowed during development** and needs to be removed during submission. Experimental APIs should never be used in any add-ons you will be distributing.

### What are the supported mime types/file formats for exported content?

The supported file types for exported content are **"image/jpeg" (jpg format), "image/png" (png format), "video/mp4" (mp4 format)** and **"application/pdf" (pdf format)**.

### What are the supported file formats for imported content in Adobe Express?

The supported file types for imported audio content are **aac, adts, ai, avi, crm, f4v, gif, jpeg, jpg, m1v, m2p, m2t, m2ts, m4a, m4v, mov, mp3, mp4, mpeg, mpg, msvideo, mts, png, psd, psdt, quicktime, ts, tts, wav, webm, webp, wmv, xm4a, xwav, 264, 3gp**.

### Are animated GIF's supported when importing or dragging content to the document?

Yes, however, there are [technical requirements](https://helpx.adobe.com/express/create-and-edit-videos/change-file-formats/import-gif-limits.html) and certain handling for each scenario. The requirements are summarized below for reference, and the handling that will take place when importing vs drag and drop follow:

- **Maximum resolution:** 1080px
- **Maximum size:** 10 MB
- **Maximum GIFs per scene:** 7

**Importing gifs:** You should use the [`addAnimatedImage()`](../references/addonsdk/app-document.md#addanimatedimage) method when you want to import an animated GIF by default. It will be added as an animated GIF to the document as long as it fits [the size criteria for animated GIF's](https://helpx.adobe.com/express/create-and-edit-videos/change-file-formats/import-gif-limits.html). In the event that it does not fit the criteria, only the first frame will be added. **Note:** Though [`addImage()`](../references/addonsdk/app-document.md#addaudio) supports the `gif` file type, if an animated GIF is passed in, only the first frame will be added.

**Drag and drop:** If the content being dragged is an animated GIF, it will be added as an animated GIF to the document, as long as it fits [the size criteria for animated GIF's](https://helpx.adobe.com/express/create-and-edit-videos/change-file-formats/import-gif-limits.html). In the event that it doesn't fit the size criteria, an error toast will be shown to the user.

### Why do I receive a "No 'Access-Control-Allow-Origin' header is present on the requested resource" error?

This error message indicates that the server that the JavaScript code is making a request to did not include the proper CORS (Cross-Origin Resource Sharing) headers in its response. Please see [this section on CORS](../guides/develop/context.md#cors) for more details on handling CORS with your add-on.

### Is [`SharedArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) supported?

No, `SharedArrayBuffer` is not currently available to use with your add-ons.

### Which browsers and operating systems are currently supported?

Please see the [Adobe Express System requirements](https://helpx.adobe.com/express/system-requirements.html) for what's currently supported.

### How does Adobe use my add-on’s data?

Adobe only instruments and reports on user behaviors related to discovering and managing their add-on, including searching for, installing, running, sharing (via link), and uninstalling an add-on.

Adobe does not instrument, store, or report on any action that the user takes within the add-on’s UI. Therefore, Adobe does not capture any user data related to 3rd party services, licenses, or user accounts, including personal information, except that which is already made directly available to Adobe through general usage of our products.

### Where can I request new add-on features or suggest ideas?

You can head over to the [Adobe Express UserVoice forum](https://adobeexpress.uservoice.com/forums/951181-adobe-express) to request features, suggest integration ideas and more.

### Why does the CLI return the error: "Login failed. Please try again.", though I didn't have a chance to login because the browser never opened?

This can happen due to a permissions issue, and the `~/Library/Application Support/Adobe/CCWebAddOn` doesn't get created. This can be fixed by creating the folder and modifying the permissions to allow write.

### What mime type is returned from a PDF that was exported with the `createRenditions` method?

The mime type returned from a PDF generated using the [`createRenditions`](../references/addonsdk/app-document.md#createrenditions) API is `application/pdf`.

### The latest version of the CLI is not automatically installing when I run the `npx` command to create a new add-on.

You can force it to install by clearing the npx cache first with `npx clear-npx-cache`, or by specifying the version in the command, i.e.: `npx @adobe/create-ccweb-add-on@1.1.1 my-add-on`.

### I'm trying to use a newly released feature, but it seems to be unavailable?

If you are trying out a newly released feature in your add-on and have an instance of Adobe Express still open in a browser tab from before, you will need to refresh the page to ensure the latest release is loaded before trying out a new feature.

### Why is my add-on not visible in the EU region?

This could be due to incomplete or outdated trader information in your [publisher profile](https://new.express.adobe.com/add-ons?mode=submission). Please make sure all required details are updated and accurate.

### How can I update my trader details in the publisher profile after submission?

To update only your trader details in the publisher profile after submission, please contact our team at [ccintrev@adobe.com](mailto:ccintrev@adobe.com). At this time, we are not processing change requests for other fields in the publisher profile.

### What happens if an EU user has a deep link to my add-on and I am not compliant with the European Union Digital Services Act (DSA) trader requirements?

If you are not compliant with the European Union Digital Services Act trader requirements, an EU user with a deep link to your add-on will not be able to install it. They will see a banner with a message indicating the compliance issue.

### Can an EU user still use my add-on if they have already installed it, but I am not compliant with the DSA trader requirements?

Yes, if an EU user has already installed your add-on, they will still be able to use it even if you are not compliant with the DSA trader requirements. However, they will see a banner with a message indicating the compliance issue.

### Why is the CLI failing with an Invalid URL error when creating a new add-on on Windows?

There's a known issue with running certain versions of Node.js on Windows with the CLI currently. Specifically, `v22.14.0` and `v18.20.7` have been found to fail with the following error:

```bash
Creating a new Add-on ...
This may take a minute ...

√ Please select a template which you want to scaffold the Add-on project with » [javascript]: Get started with Add-on development using JavaScript
√ Do you want to include document sandbox runtime? » Yes
err:: TypeError: Invalid URL
    at new URL (node:internal/url:818:25)
    at Object.fileURLToPath (node:internal/url:1505:12)
    at WxpAddOnFactory._copyTemplateFiles (file:///C:/Temp/abc/node_modules/@adobe/create-ccweb-add-on/dist/app/WxpAddOnFactory.js:131:39)
    at WxpAddOnFactory.create (file:///C:/Temp/abc/node_modules/@adobe/create-ccweb-add-on/dist/app/WxpAddOnFactory.js:90:18)
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
    at async CreateCCWebAddOn.run (file:///C:/Temp/abc/node_modules/@adobe/create-ccweb-add-on/dist/commands/create.js:90:9)
    at async CreateCCWebAddOn._run (C:\Temp\abc\node_modules\@oclif\core\lib\command.js:108:22)
    at async Config.runCommand (C:\Temp\abc\node_modules\@oclif\core\lib\config\config.js:328:25)
    at async Object.run (C:\Temp\abc\node_modules\@oclif\core\lib\main.js:89:16) {
  code: 'ERR_INVALID_URL',
  input: '.\\file:\\C:\\Temp\\abc\\node_modules\\@adobe\\create-ccweb-add-on\\dist\\templates\\javascript-with-document-sandbox'
}

Aborting installation.
Unexpected error. Please report it as a bug:
TypeError: Invalid URL
```

If you encounter this issue, please update your Node.js version to `v20.11.0` and try again.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Adobe Express Add-on Development
  - Express Editor
  - Code Playground
  - In-app editor
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
  - Add-on dev tool
  - Express Document
title: Code Playground
description: A guide to using the Code Playground in Adobe Express.
contributors:  
  - https://github.com/padmkris123
  - https://github.com/hollyschinsky
  - https://github.com/ErinFinnegan
  - https://github.com/undavide
---

# Code Playground

The Code Playground is an in-app lightweight code editor for fast and effortless prototyping.

## What is Code Playground?

Code Playground provides developers with a low-barrier entry point for add-on development, allowing you to experiment and iterate on ideas directly without any setup, from within Adobe Express. From learning the basics to rapidly prototyping advanced concepts, Code Playground accommodates all stages of add-on development.

## Who Should Use Code Playground?

The Code Playground is designed for:

- **Beginners**: New developers who want to experiment with Adobe Express add-on development without setting up a full development environment.
- **Prototypers**: Developers who need to quickly test concepts or ideas before implementing them in a full add-on project.
- **Learners**: Those who are learning the Document APIs and want to see immediate results of their code.
- **Experienced Developers**: Seasoned developers who want to test specific API functionality or debug isolated code snippets.
- **Designers**: UX/UI designers who want to experiment with add-on interfaces without extensive coding setup.

## Features

<br/>

| Feature | Description |
|---------|-------------|
| **Real-Time Preview** | See your changes as you code, allowing for immediate feedback and faster adjustments. |
| **Effortless Prototyping** | Quickly turn ideas into add-ons with minimal setup. |
| **Rapid Implementation** | Fast-track your prototype to a product by directly pasting your code into an add-on template. |
| **Script Mode** | An easy way to interact with the Document APIs quickly. |
| **Programming Assistance** | Typed definitions and auto-completion. |
| **Default Boilerplate Code** | Default boilerplate code for each tab helps you get started quickly. |
| **Local Persistence** | Save your work to your browser's local storage and resume where you left off, preventing accidental loss. |
| **Keyboard Shortcuts** | Use keyboard shortcuts to save, run, and reset your code quickly. |

<!-- Check out the video below for a quick introduction to the add-on playground features.

<br/><br/><div style="display: flex; justify-content: center;">

 <iframe width="560" height="315" src="https://www.youtube.com/embed/j6KS6CXZmKo?si=j4kX8gItWbm1ZDVz" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div><br/> -->

## Development Workflow Use Cases

The Code Playground is designed to support the following development workflow use cases:

- **Experiment First**: Test your ideas and API interactions before committing to full add-on development.
- **Learn as You Go**: Master the basics of the Document APIs and [Add-on SDK](../../references/addonsdk/index.md) without complex setup requirements.
- **Prototype Quickly**: Build and test features in minutes instead of hours with instant feedback.
- **Bridge to Production**: Develop core functionality in Playground before moving to a complete project environment.
- **Debug with Ease**: Isolate and fix specific issues by testing API calls outside your production code.

## How to Access Code Playground

### Step 1: Enable Add-on Development Mode

- Click the avatar icon in the top right corner of Adobe Express, then the gear icon to open the "Settings".
- Enable **Add-on Development** if it's not already enabled:

  ![Adobe Express Settings](./img/settings_alt.png)

### Step 2: Open Code Playground

- With any document open, click the **Add-ons** button in the left rail.
- Select the **Your add-ons** tab.
- Toggle on **Code Playground** at the bottom of the panel:

  ![Adobe Express Code Playground Toggle](./img/toggle-playground.png)

- Once enabled, the playground window will open, allowing you to begin coding immediately:

  ![Adobe Express Code Playground Open](./img/playground-open.png)
  
## Choose Your Development Mode

The playground offers two distinct development modes:

- [**Script Mode**](#script-mode): Experiment with the Adobe Express [Document Sandbox](../../references/document-sandbox/index.md). This mode is equivalent to writing code in the `sandbox/code.js` file in an add-on project running locally, but allows you to rapidly test in Express directly.
- [**Add-on Mode**](#add-on-mode): Test and iterate on your [Add-on UI](../../references/addonsdk/) and functionality with no setup required.

<br/>

| Comparison Factor | Script Mode | Add-on Mode |
|--------------------|-------------|-------------|
| **Purpose**        | Quick document manipulation tests | Complete add-on UI and functionality |
| **Environment**    | Document Sandbox only | Both iframe and Document Sandbox |
| **API Access**     | [Document APIs](../../references/document-sandbox/document-apis/index.md) | [Document APIs](../../references/document-sandbox/document-apis/index.md) + [Add-on UI SDK](../../references/addonsdk/index.md) |
| **Global Await**   | Yes | No |
| **Automatic Imports** | Yes | No |
| **UI Components**  | No UI building | Full HTML/CSS/JS interface creation |
| **Best For**       | Testing document operations | Building complete add-ons |

## Script Mode

### When to Use Script Mode

- To learn how the Document APIs work
- To quickly experiment with Document API calls without UI considerations

**Note:** The code you write in this mode is equivalent to the code you would write and use in the `sandbox/code.js` file in an add-on project running locally.

### How to Use Script Mode

1. Select the **Script** button in the top left corner of the playground window.
2. Enter your [Document API](../../references/document-sandbox/document-apis/index.md) code in the editor. Manipulate the document directly, add shapes or text, change styles, and more using the automatically available [`editor`](../../references/document-sandbox/document-apis/classes/Editor.md) object.
3. Execute your script by clicking the **Run Code** button in the right corner of the playground window to see changes in the current document.

  ![Code Playground Script Mode](./img/script-mode.png)

4. If you want to use Document APIs that are currently marked experimental, click on the properties icon to open the [Manifest JSON](../../references/manifest/index.md#requirements) editing modal and toggle **experimentalApis**:

  ![Script Mode Manifest Settings](./img/manifest-props-script.png)

5. Head over to our [How-to guides](../develop/how_to.md) to see some examples of using the Document APIs with example code snippets. For instance, the guides:

    - [How to Use Geometry](../develop/how_to/use_geometry.md)
    - [How to Use Color](../develop/how_to/use_color.md)
    - [How to Use Text](../develop/how_to/use_text.md)

#### Key Considerations

- **No UI**: Script mode is focused on Document API interactions and does not support building a user interface. If you want to create a UI, switch to [Add-on mode](#add-on-mode).

- **Global Await**: The script runtime provides a global `async` wrapper, allowing you to use `await` directly when executing asynchronous code, without needing to wrap it in an `async` function. This is particularly useful for API calls that return promises, where an `await` is needed to pause the execution of an `async` function until the Promise is resolved or rejected. For example, loading a font is an asynchronous operation, but in Script mode you can use `await` directly to pause the execution of the script until the font is loaded, ie:

```js
// The script runtime provides an async wrapper to allow this:
const textNode = editor.context.selection[0];
const lato = await fonts.fromPostscriptName("Lato-Light");
```

In contrast, in [**Add-on mode**](#add-on-mode) you will need to manually wrap the code in an `async` function and use `await` in it, ie:

```js
//sandbox.code.js or Document JS tab
loadFont: async () => {
  const textNode = editor.context.selection[0];
  const lato = await fonts.fromPostscriptName("Lato-Light");  
}
```

- **Automatic Imports**: Script mode automatically imports the `express-document-sdk` modules, so you don't need to add import statements for the [Document APIs](../../references/document-sandbox/document-apis/index.md). However, if you do add import statements, it wont harm anything.

<InlineAlert slots="text" variant="info"/>

Once you switch to the [Add-on mode](#add-on-mode) or to your local add-on development environment, you will need to make sure to handle your `async` functions and `import` statements manually.

## Add-on Mode

### When to Use Add-on Mode

- To develop and test an add-on directly in Adobe Express, without having to set up a full development environment.
- To prototype an add-on before building a full project.
- To iterate quickly on your add-on's UI and logic.

### How to Use Add-on Mode

1. Click on the **Add-on** button (next to the **Script** button in the top left corner of the playground window).
2. Write code for your add-on in each of the supplied tabs (described below). This includes HTML, CSS, and JavaScript code that will run in the iframe UI or in the Document Sandbox to interact directly with the Express document (optionally).
3. Click **Run Code** to execute your add-on. Your add-on should open in an iframe on the right side of the Adobe Express window, ie:

  ![Code Playground Add-on Mode](./img/addon-mode.png)

4. If you need to set [manifest properties](../../references/manifest/index.md) for your add-on (ie: if you want to use APIs that are currently marked experimental, set permissions, OAuth domains etc), click on the properties icon to open the Manifest JSON editing modal:

  ![Add-on Mode Manifest Settings](./img/manifest-props-addon.png)

### Add-on Mode Tabs

The Add-on mode features four tabs for organizing your code:

1. **HTML Tab**

  This tab is for writing HTML code that defines the structure of your add-on's user interface. You can create elements like buttons, text fields, and layout containers here. Functionally, this tab mirrors the role of the `index.html` file you'd use in a typical add-on project.

2. **CSS Tab**

  Style your add-on's HTML elements in this tab. Create a visually appealing interface consistent with Adobe Express design patterns. This section corresponds to the `styles.css` file in a standard add-on project.

3. **Iframe JS Tab**

  This tab is for writing JavaScript code that runs in the iframe context of your add-on. Here, you can interact with:

  - The [Add-on UI SDK (`addOnUISdk`)](../../references/addonsdk/index.md)
  - The DOM elements in your HTML
  - Event handlers for your UI components

  This environment corresponds to the code you would typically write in your `index.js` or UI JavaScript files in a full add-on project.

4. **Document JS Tab**

  This tab is where you write JavaScript code that interacts directly with the Adobe Express document. It runs in the [Document Sandbox](../../references/document-sandbox/index.md) environment and gives you access to:

  - Document manipulation capabilities with the [Document APIs](../../references/document-sandbox/document-apis/index.md)
  - [Communication APIs](../../references/document-sandbox/communication/index.md) to facilitate interaction between the iframe context and the Document Sandbox.

  The Document JS tab corresponds to the code typically found in the `code.js` file of a complete add-on project.

## Transitioning from Script Mode to Add-on Mode

Once you've tested your code in Script mode, you can easily transition it into the [Add-on mode](#add-on-mode) to build a user interface around your new functionality. Here's how:

1. Use the **Copy** button in the right corner to quickly copy your code to the clipboard.
2. Click the **Add-on** button to enter [Add-on mode](#add-on-mode).
3. Paste the code into the [**Document JS**](#add-on-mode-tabs) tab. **Note:** Don't forget you'll need to add the `import` statements for the Document APIs and handle your `async` functions manually in this mode.
4. Modify your script code to be used in the add-on context along with your front-end logic in the [**HTML**](#add-on-mode-tabs), [**Iframe JS**](#add-on-mode-tabs), and [**CSS**](#add-on-mode-tabs) tabs. Use the initial sample code provided as a reference.
5. If you set any manifest properties (ie: **experimentalApis**) while in [Script mode](#how-to-use-script-mode), make sure to set the same in the [Add-ons mode - Edit Manifest JSON Modal](#how-to-use-add-on-mode) as well. These settings only apply to the context of the development mode you're in.
6. Click the **Run Code** button to execute your code within the context of your add-on.

## Workflow Tips

Keyboard Shortcuts, local save and session management are all designed to help you get the most out of the Code Playground.

### Keyboard Shortcuts

<br/>

| Action | Windows/Linux | macOS |
|--------|---------------|-------|
| **Save** | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd> | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd> |
| **Run** | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Return/Enter</kbd> | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>Return/Enter</kbd> |
| **Reset** | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>X</kbd> | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>X</kbd> |
| **Increase font size** | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Plus (+)</kbd> | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>Plus (+)</kbd> |
| **Decrease font size** | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Minus (-)</kbd> | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>Minus (-)</kbd> |
| **Switch between tabs** | <kbd>Ctrl</kbd> + <kbd>1, 2, 3, 4</kbd> | <kbd>Cmd</kbd> + <kbd>1, 2, 3, 4</kbd> |
| **View the typings suggestions** | <kbd>Ctrl</kbd> + <kbd>space</kbd> | <kbd>Cmd</kbd> + <kbd>space</kbd> |

<InlineAlert slots="header,text1" variant="success"/>

#### TIP

Use the "**...**" button in the top right corner of the playground window to reference the available keyboard shortcuts, start a new session, link to documentation and more.

### Saving Your Work

The Code Playground features local persistence to help prevent the loss of your work. This functionality ensures that your code is stored in your browser's local storage, providing a safeguard against accidental data loss.

Code in the playground is ***not saved automatically***. To ensure it's saved, you need to take one of the following steps:

  1. Save your work using the [keyboard shortcut for Save](#keyboard-shortcuts).
  2. Run the code via the **Run Code** button or with the [keyboard shortcut for Run](#keyboard-shortcuts).
  3. Exit the playground (with the **X** in the upper right corner).

If you don't want to save your work at any time, use the [keyboard shortcut to Reset](#keyboard-shortcuts).

<InlineAlert slots="header, text1" variant="warning"/>

#### IMPORTANT

- Only your most recent session is saved.
- Storage is browser-specific (not synced across devices).
- Code is not saved in incognito/private browsing modes.
- Clearing browser data will delete saved code.

### Resuming Sessions

There are two ways to resume working on your last saved session:

1. **Via the Add-ons Panel:**

   - With any document open, click the **Add-ons** button in the left rail.
   - Select the **Your add-ons** tab.
   - Toggle on **Code Playground** at the bottom of the panel.

   ![Code Playground Add-on Mode](./img/playground-on.png)

2. **Via the Your add-ons Page:**

   - The **Your add-ons** page where you manage your add-ons now features a dedicated section for the playground, allowing you to quickly access your last session or create a new one.
   - Find the **Playground Sessions** section in the **Your add-ons** page.
   - Access your last session or create a new one with one click.

  ![Manage Your add-ons page](./img/playground-sessions.png)

<InlineAlert slots="header, text1" variant="info"/>

#### Accessing "Your add-ons" Page

- **Without a document open:** Click the **Add-ons** button in the left rail, then click the **Add-on development** toggle in the top right.
- **With a document open:** Click the **Add-ons** button in the left rail, select the **Your add-ons** tab, then click the "Manage add-ons" link in the Add-on Testing section.

## Resources

- **How-To Guides:** Begin by experimenting with the code snippets found in our [how-to guides](../develop/how_to.md) to kickstart your development.
- **SDK/API References:** Discover more about what you can do in your add-on by exploring our [SDK References](../../references/index.md).
- **Code Samples:** Get inspired by checking out [our code samples](../../samples.md) to see what's possible.
- **Ask Questions:** Chat with fellow developers on [Discord](http://discord.gg/nc3QDyFeb4).

## Next Steps: Build Your Add-on Locally

After experimenting with the Code Playground and when you're ready to build out a full-blown add-on in a local development environment:

1. Follow our [Quickstart Guide](../getting_started/quickstart.md) to get your environment set up and your first add-on project created quickly.
2. Copy the code from the Code Playground [Add-on mode tabs](#add-on-mode-tabs) to the corresponding files in your new project. **Note:** Don't forget, if you're copying code from Script mode into your `sandbox/code.js` file, you'll need to add the `import` statements for the Document APIs and handle your `async` functions manually.
3. Copy the JSON from the [Manifest JSON Editor](#how-to-use-add-on-mode) in the Code Playground into the `src/manifest.json` file in your new project.
4. Run your add-on locally using the [Adobe Express CLI](../getting_started/quickstart.md) to test and see your changes in real-time.

## FAQs

### What is the Adobe Express Code Playground?

The Adobe Express Code Playground is a lightweight code editor designed for fast and effortless prototyping. It allows you to experiment with simple code snippets to build and refine add-ons, quickly turning ideas into functional features.

### Is it free to use?

Yes, the Code Playground is free to use. You can access all its features without any cost and start prototyping and creating add-ons right away.

### Do I need coding experience?

While some basic coding knowledge is helpful, Playground is designed to be beginner-friendly and accessible. Its intuitive interface and simple code snippets make it easier for both experienced developers and those newer to coding to create and test add-ons.

### How do I start creating add-ons?

Getting started is simple. activate the playground, experiment with code snippets, and start building your add-ons. Use the real-time preview feature to see your changes instantly and iterate on your ideas with ease.

### Where can I go for help?

[Join our Discord](http://discord.gg/nc3QDyFeb4) to chat with the add-on developer community.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: Quickstart
description: This is the Quickstart page
contributors:
  - https://github.com/hollyschinsky
  - https://github.com/undavide
---

# Development Tools

## Using the CLI

The add-on CLI (Command Line Interface) is the main tool that enables you to develop, test, and package add-ons for our platform. With the add-on CLI, you can create a new add-on project, build and test your add-on locally, and package your add-on for distribution.

Here are some key features of the add-on CLI:

- **Project creation:** The add-on CLI provides a command to create a new add-on project with a basic file structure and configuration.
- **Local development:** The add-on CLI includes a built-in server that allows you to test your add-on locally before deploying it to our platform.
- **Live reloading:** The add-on CLI watches your project files for changes and automatically reloads the server when a change is detected.
- **Packaging:** The add-on CLI provides a command to package your add-on for distribution, including creating a ZIP file that can be uploaded to our platform.

### CLI `create` options

The table below shows the list of arguments that can be specified with the CLI create command (ie: `npx @adobe/create-ccweb-add-on`):

| Argument      | Optional | Default Value                                | Description                                                                                                          |
| ------------- | -------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `add-on-name` | No       |                                              | Name of the add-on. A new add-on project with this argument will be created in the user's current working directory. |
| `template`    | Yes      | none, you will<br/> be prompted from the CLI | The template to use for creating the add-on. |
| `verbose`     | Yes      | false                                        | Setting this argument enables the verbose flag on the underlying operations. |

For instance, the following command would specify all possible arguments:

```bash
npx @adobe/create-ccweb-add-on my-addon --template react-typescript --verbose
```

<InlineAlert slots="heading, text1, text2, text3, text4, text5" variant="info"/>

#### CLI troubleshooting <!-- 👈 will not render -->

See the [templates](#templates) section for the currently supported template values.

`npx` is an `npm` package runner that can execute packages without installing them explicitly. If needed, please run this command to clear the `npx` cache to ensure the latest version of the CLI is invoked.

```bash
npx clear-npx-cache
npx @adobe/create-ccweb-add-on my-addon 
```

The above may prove useful when updated versions of the CLI are released. If you want to read each individual CLI command manual page, run them via `npx` with the `--help` flag, for example:

```bash
npx @adobe/ccweb-add-on-scripts start --help  
```

### `start` script options

The table below shows a list of arguments that can be specified with the `start` script on your add-on project, which starts up the add-on in a local server:

| Argument  | Optional | Default Value | Description                                                                  |
| --------- | -------- | ------------- | ---------------------------------------------------------------------------- |
| `src`     | Yes      | `src`         | Directory where the source code and assets for the add-on is present.        |
| `use`     | Yes      |               | Transpiler/bundler to be used. For example, webpack.                         |
| `port`    | Yes      | `5241`        | Local development server port.                                               |
| `verbose` | Yes      | false         | Setting this argument enables the verbose flag on the underlying operations. |

For instance, to specify a port of `8080` instead, use the following command:

```bash
npm run start -- --port 8080
```

To specify you want to use `webpack` AND port `8080`:

```bash
npm run start -- --use webpack --port 8080
```

<InlineAlert slots="text" variant="info"/>

The extra arguments are unnecessary unless you do not want to use a transpiler/bundler or use the default port of `5241`. Also, note that all of the templates other than the `javascript` template are pre-configured to use webpack by default and the `--use webpack` is automatically added when you run the `build` and `start` commands. Take a look at the `scripts` property in the `package.json` of those templates and you will see the following:

```json
"scripts": {
    "clean": "ccweb-add-on-scripts clean",
    "build": "ccweb-add-on-scripts build --use webpack",
    "start": "ccweb-add-on-scripts start --use webpack"
}
```

## Templates

The add-on CLI contains built-in, pre-configured templates to allow you to create an add-on project based on your favorite development stack in the quickest possible manner. There are currently five base template options based on popular web development trends. The table below summarizes the templates and their associated frameworks.
<br/>

| Template         | Framework        |
| ---------------- | ---------------- |
| `javascript`       | JavaScript       |
| `swc-javascript`       | JavaScript with Spectrum Web Components support     |
| `swc-typescript`       | TypeScript with Spectrum Web Components support     |
| `react-javascript`  | React with JavaScript |
| `react-typescript` | React with TypeScript |

As well as the following five template options, which include support for the [Document Sandbox APIs](../../references/document-sandbox/):

| Template         | Description        |
| ---------------- | ---------------- |
| `javascript-with-document-sandbox`  | JavaScript with Document Sandbox support.  |
| `swc-javascript-with-document-sandbox`  | JavaScript and Spectrum Web Components with Document Sandbox support.  |
| `swc-typescript-with-document-sandbox`  | TypeScript and Spectrum Web Components with Document Sandbox support.      |
| `react-javascript-with-document-sandbox`  | React and JavaScript with Document Sandbox support.|
| `react-typescript-with-document-sandbox` | React and TypeScript with Document Sandbox support.|

You can supply any of the above template names after the `--template` parameter:

```bash
npx @adobe/create-ccweb-add-on <add-on-name> --template <template>
```

For instance, the following is an example of a command that will create an add-on based on the `react-javascript` template:

```bash
npx @adobe/create-ccweb-add-on helloworld-react-js --template react-javascript
```

and below is how you could specify the `react-javascript-with-document-sandbox` template:

```bash
npx @adobe/create-ccweb-add-on helloworld-react-js-doc-sandbox --template react-javascript-with-document-sandbox
```

### No template parameter

The template parameter is optional, and the CLI will prompt you to choose from a list of template options if it's excluded. For instance, if you use just the base CLI command:

`npx @adobe/create-ccweb-add-on <add-on-name>`

you will see the following prompt from the CLI:

![doc sandbox prompt](./img/CLI-template-prompt.png)

which shows the five base template options to choose from, followed by a prompt to ask if you want to add the Document Sandbox support once you choose the base template.

![cli doc sandbox prompt](./img/CLI-doc-sandbox.png)

You will also see a message in the CLI output notifying you of which template the project was scaffolded with for reference:

![template scaffolding message](./img/CLI-scaffold-message.png)

<InlineAlert slots="text1, text2" variant="warning"/>

Please note that to use [Spectrum Web Components](/guides/design/user_interface.md#spectrum-web-components) in your add-on's UI, Webpack is required. All templates, except for the `javascript` and `javascript-with-document-sandbox` templates, are pre-configured to use Webpack by default.

If you don't want to use TypeScript or React, please refer to [this sample add-on](https://github.com/AdobeDocs/express-add-on-samples/tree/main/contributed/swc) as an example of a JavaScript/Webpack project with Spectrum Web Components support.

When the scaffolding is complete, you will see the following message, prompting you to navigate to the newly created project directory and start the local development scripts:

![CLI completed message](./img/CLI-completed.png)

## Manifest

A `manifest.json` file is required in every add-on project. The manifest provides details including important metadata about your add-on and how it should behave. Be sure to consult the [manifest schema reference](../../references/manifest) to ensure that your `manifest.json` file is properly formatted and includes all of the necessary properties and values.

## Add-on Development Tools Panel

The **Add-on Development** tools panel provides useful logging details indicating the status of your add-on, as well as action buttons to allow for refreshing and clearing the data associated with your add-on. The panel is shown in the screenshots below for reference:

<InlineAlert slots="text" variant="info"/>

The **Refresh** button can be used to reload your add-on's code and resources, and the **Clear Storage** button allows you to clear any data stored by your add-on.

![add-ons tools screenshot](./img/add-on-devtools.png)
![manifest error screenshot](./img/manifest-error.png)
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: Intro
description: This is the Intro page for Getting Started
contributors:
  - https://github.com/hollyschinsky  
hideBreadcrumbNav: true
---

# Getting Started Overview

This section provides everything you need to know to get started building add-ons for Adobe Express.

## Introduction

At a high level, add-ons refer to any feature distributed independently from the core Adobe Express that a user can enable or install to extend the functionality. Adobe provides some built-in add-ons out of the box, but 3rd party developers also have the opportunity to create and distribute their own add-ons by following the steps provided in this documentation.

### Getting Started Steps

The [Quickstart](quickstart.md) steps you will follow to get started building your first add-on include:

1. [Set up](quickstart.md#prerequisites) your local environment.
1. [Create a new add-on project](quickstart.md#step-1-create-your-add-on-project)
1. [Build and start your add-on](quickstart.md#step-2-build-and-start-your-add-on).
1. Log in to [Adobe Express](https://new.express.adobe.com/new).
1. Enable the [developer mode](quickstart.md#step-3-enable-add-on-development-mode-first-time-only) (one time only).
1. [Load and run your add-on](quickstart.md#step-4-load-and-run-your-add-on) directly in Adobe Express.
1. [Continue developing your add-on](quickstart.md#step-5-edit-your-add-on), seeing your changes immediately appear in, allowing you to iterate quickly.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: Quickstart
description: A quickstart guide to getting started building your first Adobe Express add-on
contributors:
  - https://github.com/hollyschinsky
  - https://github.com/undavide
---

# Quickstart

This quickstart guide will help you create and run your first add-on, a simple hello world add-on built with plain JavaScript.

## Introduction

Check out this short video below for a quick visual introduction to the steps you'll take to create your very first add-on.<br/><br/>

<div style="display: flex; justify-content: center;">
<iframe width="560" height="315" src="https://www.youtube.com/embed/kSq4ykQGOdo" title="Creating Your First Add-on | How to Create Add-ons in Adobe Express" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>

<!-- <iframe src="https://drive.google.com/file/d/1NpKsxGJyA2DeH0xPhLyTr17cdy9awhYG/preview" width="775" height="485" allow="autoplay" style="border: 0"></iframe> -->

<br/>

## Prerequisites

- [NodeJS](https://nodejs.org/en/download/) (major version of 16 or greater) and [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) (major version of 8 or greater) installed
- Familiarity with programming in HTML, CSS and JavaScript
- An Adobe Express account (use an existing Adobe ID or simply create one for free).

### Add-on CLI

The **[Adobe Express add-on CLI](dev_tooling.md#using-the-cli) (Command Line Interface) is required for add-on development** and allows you to create and host Adobe Express add-ons directly from your local machine.

## Step 1: Create your add-on project

Open your terminal and run the following command:

```bash
npx @adobe/create-ccweb-add-on hello-world --template javascript-with-document-sandbox
```

This command will create a new add-on based on pure JavaScript with Document Sandbox support (the set of APIs that allow you to interact with Adobe Express documents).

- `hello-world` is the name of the add-on you are creating.
- The `--template` flag specifies the template to use for the add-on; in this case, `javascript-with-document-sandbox`. The parameter is optional, and when missing, the CLI will prompt you to choose one from a list.

The [Templates section](dev_tooling.md#templates) on the **Development Tools** page provides a list of available options; if your add-on doesn't need to manipulate documents, you may want to pick a sandbox-free template (e.g., `javascript` instead of `javascript-with-document-sandbox`).

**For Windows Users:** If you're using the CLI in the terminal, you'll need to add `openssl` to the `path` under Environment Variables. If `git` is installed, `openssl` can be found at `C:\Program >Files\Git\usr\bin`. Otherwise, you can download `git` from https://git-scm.com/downloads, and add the directory location to the `path` variable in your Environment Variables.

<InlineAlert slots="heading, text1, text2, text3, text4, text5" variant="info"/>

#### CLI troubleshooting <!-- 👈 will not render -->

`npx` is an `npm` package runner that can execute packages without installing them explicitly.

Please run this command to clear the `npx` cache and ensure the latest version of the CLI is invoked.

```bash
npx clear-npx-cache
npx @adobe/create-ccweb-add-on hello-world
```

The above may prove useful when updated versions of the CLI are released. If you want to read each individual CLI command manual page, run them via `npx` with the `--help` flag, for example:

```bash
npx @adobe/ccweb-add-on-scripts start --help
```

## Step 2: Build and start your add-on

Next, execute the following commands to change into the newly created **hello-world** add-on folder, `build` the add-on, and `start` the add-on in a local server:

```bash
cd hello-world;
npm run build;
npm run start;
```

The `start` script will display messages like the following after it executes:

```bash
Done. Your add-on 'hello-world' is hosted on: https://localhost:5241/

You can now sideload your add-on by enabling the Developer Mode in the Add-ons panel.
```

## Step 3: Enable add-on development mode (first-time only)

- Navigate to [Adobe Express](https://new.express.adobe.com/).
- Click on your user avatar in the top righthand corner and choose **Settings**.

![Dev settings toggle on](./img/avatar-settings-v2.png)

- If you haven't already, click the **Accept and Enable** button to enable the add-on development switch (which is grayed out). Clicking the "Go to Developer Terms of Use" will open them in a new tab.

![Accept and enable](./img/accept-and-enable.png)

- When you have accepted the terms of use, the switch becomes available and should be toggled on.

![Dev settings on](./img/enabled-development.png)

## Step 4: Load and run your add-on

- Navigate your browser to [Adobe Express](https://new.express.adobe.com/new) and **create a new project**—a blank one will suffice.
- Click the **Add-ons** icon on the left rail.

<InlineAlert slots="text1, text2" variant="info"/>

It's possible to access the **Add-ons** from the home page as well (i.e., without the need to open a new project first). In this case, you must follow the listing creation outlined [here](../distribute/private-dist.md#step-1-create-a-new-add-on-listing) first.

For simplicity's sake, this Quickstart guide covers the document creation method.

- Notice there are two tabs: **Discover** and **Your add-ons**.

![add-on tabs](./img/add-on-tabs-v2.png)

- Click on the **Your add-ons** tab to access the **Add-on Development** tools panel, and toggle on the **Add-on testing** switch.

![Dev testing toggle on](./img/launchpad-toggle-v2.png)

- Once clicked, a modal will appear where you will provide the URL of your locally hosted add-on.

  **Note:** Use the default `https://localhost:5241` supplied unless you are intentionally using a different port.

  Select the _I understand the risks of loading an add-on from an external server_ checkbox and press the **Connect** button.

![Add-on connect modal](./img/connect-modal-v2.png)

- The **Add-on Development** panel will expand and show a message that the add-on is connected in the log, along with the name and version of your add-on. You can click on the down arrow icon to collapse the panel.

![Hello World add-on connected](img/hello-world-loaded-log-open-v2.png)

- To run your add-on, simply click on it from the **In development** panel. Your add-on should now be displayed in the add-ons panel on the right side of your Adobe Express window:

![Hello World add-on running](img/hello-world-run-v2.png)

## Step 5: Edit your add-on

While your add-on is still loaded and running, open the `src/index.html` file and update the **"Create Rectangle"** string in the `<button>` below.

![](./img/vs-code-create-rectangle.png)

To something else, like **"Draw Rectangle"**.

![](./img/vs-code-draw-rectangle.png)

Note that the terminal where your add-on runs will display messages showing that the `src` has been rebuilt, as shown in the screenshot below. This is due to the hot module reload feature built into the CLI.

![hot reload](./img/hot-reload-v2.png)

Go back to your browser where the add-on is running in Adobe Express and notice the new string is automatically updated, and the **Add-on Development** panel shows that it was auto-reloaded.

![updated add-on](./img/updated-add-on-v2.png)

You can continue to update your code while your add-on is running, and the add-on will automatically be rebuilt on save.

**Manifest updates**<br/>

Any changes to the `manifest.json` will _require a manual reload of your add-on_. The **Add-on Development** panel will indicate this in the log messages, and the **Refresh** button can be used to reload the add-on directly within Adobe Express. You can try this by updating the `name` field in the `src/manifest.json` file of your running add-on from "Hello World" to, say, **"Draw Rectangle"**.

![manifest update](./img/manifest-update-v2.png)

Then, switch back to your Adobe Express window, and you should see a message that changes have been detected in your manifest.

![manifest refresh reminder](./img/manifest-refresh-reminder-v2.png)

Click the **Refresh** button, then click your add-on icon to load it again, and note the updated name in the title of your add-on as outlined below.

![manifest refresh complete](./img/manifest-refresh-complete-v2.png)

## Next steps

Congratulations! You've completed the quickstart and run your first add-on!

Next, check out the [development tools](dev_tooling.md) page to discover more details on topics to be aware of while building add-ons, followed by the rest of the [guides section](../), where you will find in-depth resources for [designing](../design/index.md), [developing](../develop/index.md), [debugging](../debug/index.md) and [distributing](../distribute/index.md) your add-ons.

If you're ready to dive into our developer platform, we highly recommend following the [tutorials](/guides/tutorials), and exploring our collection of [code samples](../../samples.md). These samples provide hands-on examples of how to use our platform SDKs and APIs and are a great resource to help you get started building your own add-ons.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: Quickstart
description: This is the Quickstart page
contributors:
  - https://github.com/hollyschinsky
---

# Setup Guide

This guide will help you set up your development environment so you can get started creating Express add-ons quickly.

## Prerequisites

- [NodeJS](https://nodejs.org/en/download/) (major version >= 16) and NPM (major version >= 8) installed.
- Familiarity with programming in HTML, CSS and JavaScript.
- The add-on CLI installed on your local machine.
- An email address associated with an Adobe ID. If you don't have one yet, you'll be taken through steps to create one in this guide.

## Add-on CLI (Command Line Interface)

To facilitate the development of add-ons, we have incorporated a command line interface (CLI). This CLI will enable you to create and run Express add-ons directly in your local machine and load them into Adobe Express in your browser. Before you can use the CLI, you must install it to your local environment.

In the [next section](quickstart.md), you will learn how to create your very first add-on, a simple "hello world" add-on that outputs a string.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: Adobe Express Add-ons Guides
description: Find the most recent documentation, code samples and resources for building add-ons for Adobe Express.
contributors:
  - https://github.com/hollyschinsky
---

<Hero slots="heading, text" background="rgb(138, 43, 226)"/>

# Overview

Adobe Express is the AI-first, all-in-one creativity app that makes it fast, easy, and fun for any user to design and share standout content.

## Add-ons

<InlineAlert slots="text" />

**Join Us: Office Hours for Adobe Express Developers** <br /><br />
Receive real-time support, have your questions answered, and connect with both experts and peers for discussions on all things related to add-ons. Join us every month on Wednesdays at 8 AM PT. [Register for our next session here](https://developer.adobe.com/developers-live).

Add-ons extend the functionality of [Adobe Express](https://new.express.adobe.com/), unlocking creative workflows for Adobe Express users. The add-ons marketplace is a dedicated platform for developers to distribute and users to discover new add-ons. Check out this quick introduction to Adobe Express add-ons to learn more, then read on to get started. <br/><br/>

<div style="display: flex; justify-content: center;">
  <iframe width="560" height="315" src="https://www.youtube.com/embed/CHBiTTN1neE" title="Introduction to Adobe Express Add-ons" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div><br/>

To discover add-ons in [Adobe Express](https://new.express.adobe.com/new):

1. Open the Adobe Express editor and [create a new file](https://new.express.adobe.com/new) or open an existing one.
2. Click on the **Add-ons** button located in the left-hand sidebar.
3. Browse through the different categories of add-ons or use the search bar to find specific add-ons.
4. Click on an add-on to view more information and to install it.

![discover add-ons image](../images/discover.png)

That's it! You can now use the installed add-ons in your Adobe Express projects.

### Use Cases

Ready to build your own? Check out these popular use cases supported by our add-on SDK for inspiration:

- Importing images and video
- Exporting renditions of images in different formats
- Connecting to external sources via OAuth 2.0
- Storing and retrieving data
- Drag-and-drop support of content to the canvas
- Retrieving manifest data
- Managing language and locale
- Retrieving the current theme and detecting theme changes

See the [implementing common use cases](develop) page and [code samples](../samples.md) for more details on how to implement the features above.

## Add-on Developer Journey

The journey to developing an add-on is outlined below:

1. Create an add-on project with the CLI. You can refer to the [Getting Started](./getting_started/) guides to help you create your first project quickly.
2. Design your UI using [Adobe's Spectrum Design System](https://spectrum.adobe.com/). This system provides guidelines and resources for designing user interfaces that follow Adobe's design language and best practices.
3. Use the [common use case implementations](./develop/), [code samples](../samples.md), and [references](../references/) to learn how to include all of the features you want to showcase in your add-on. This can help you save time and avoid common mistakes when developing your add-on.
4. [Debug and test](./debug/) your add-on using your favorite browser tools, Visual Studio Code, and the add-on logging window provided in the Adobe Express UI development environment. This will help you identify and fix any bugs or issues before distributing your add-on.
5. Distribute your add-on for public or private sharing. You can refer to the [add-on distribution guidelines](./distribute/) to learn how to package and distribute your add-on on the Adobe add-ons marketplace or privately to your clients.

If you run into any issues at any time throughout your development process, please refer to the [Debug Guides](../guides/debug/) and [FAQ](../guides/faq.md) for more help.
---
keywords:
    - Adobe Express
    - Express Add-on SDK
    - Express Document API
    - Document Model Sandbox
    - Adobe Express
    - Add-on SDK
    - SDK
    - JavaScript
    - Extend
    - Extensibility
    - API
title: Building your first add-on with the Document API
description: This is an in-depth tutorial that will guide you in the creation of a Grids add-on for Adobe Express using the Document API
contributors:
    - https://github.com/undavide
---

# Building your first add-on with the Document API

This tutorial will guide you through the creation of your first Adobe Express add-on based on the Adobe Express Document API.

## Introduction

Hello, and welcome to this Adobe Express Document API tutorial, where we'll build together a **fully functional Grid System add-on** from scratch. Grid systems are widely used in the design world to bring structure and consistency to all visual content, from flyers to web pages or social media posts.

<Media slots="video"/>

<https://www.youtube.com/watch?v=SQMYA660gII>

![](images/grids-addon.png)

Your add-on will allow users to create a variable number of rows and columns, control the spacing between them (known as the _gutter_), and apply color overlays.

### Changelog

This tutorial has been written by [Davide Barranca](https://www.davidebarranca.com), software developer and author from Italy; revision history as follows.

**January 9th, 2024**

-   Added additional information on the project's setup.
-   Renamed `createStroke()` to `makeStroke()`: according to the new naming convention, `make*` is used for plain objects and helper utilities, whereas `create*` is reserved to live document objects, e.g., `createEllipse()`.
-   Improved explanations for importing Spectrum Web Components.

**December 3rd, 2023**

-   Removed the experimental warning from the document model sandbox APIs.
-   Importing `colorUtils` instead of `utils` from `"express-document-sdk"`; the built-in `colorUtils.fromHex()` method replaces the custom `hexToColor()`.
-   In the new API, nodes don't have the `fills` property (and it's `append()` method) anymore; instead, they use `fill`, to which a `ColorFill` is assigned.

**November 29th, 2023**

-   `apiProxy()` now accepts `"documentSandbox"` as a parameter, instead of `"script"`.
-   `manifest.json` now accepts `"documentSandbox"` in lieu of the `"script"` property for the document sandbox entry point. This requires the `"@adobe/ccweb-add-on-scripts"` dependency to be updated to version `"^1.1.0"` or newer in the `package.json` file.
-   `addOnSandboxSdk` is now imported from `"add-on-sdk-document-sandbox"` (it used to be `"AddOnScriptSdk"`).
-   `editor` and other modules are now imported from `"express-document-sdk"` (it used to be `"express"`).
-   The `webpack.config.js` file has been updated to reflect the new imports (see the `externals` object) in both the `express-grids-addon` and `express-addon-document-api-template` projects.
-   `Constants` are now `constants` (lowercase), and their enumerations have changed (e.g., `BlendModeValue` is now `BlendMode`).
-   `translateX` and `translateY` have conflated in the new `translation` property.
-   The group's warning about the operations order (create, append, fill) has been removed; groups can now be created, filled and appended.

**November 21st, 2023**

-   Editor API are now called the Document API, which are part of the Document Model Sandbox.
-   Update the add-on folders to reflect the new naming convention (`script` is now `documentSandbox`).
-   Update Reference Documentation links and screenshots.

**November 6th, 2023**

-   First publication.

### Prerequisites

-   Familiarity with HTML, CSS, JavaScript.
-   Familiarity with the Adobe Express add-ons environment; if you need a refresher, follow the [quickstart](/guides/getting_started/quickstart.md) guide.
-   An Adobe Express account; use your existing Adobe ID or create one for free.
-   Node.js version 16 or newer.

### Topics Covered

<!-- List block here -->
<ListBlock slots="text1, text2" repeat="4" iconColor="#2ac3a2" icon="disc" variant="fullWidth" />

[iframe and Document Model Sandbox communication](#the-communication-api)

[Spectrum Web Components](#designing-the-ui-with-spectrum-web-components)

[Adobe Express Document API](#the-document-api)

[Color Pickers](#designing-the-ui-with-spectrum-web-components)

[Nodes insertion point](#creating-the-first-shape)

[Creating and manipulating shapes](#creating-the-first-shape)

[Grouping elements](#organizing-the-code)

[Context permanence](#deleting-grids)

![](images/grids-addon-animation.gif)

### Getting Started with the Document API

As part of the [Document Model Sandbox](/references/document-sandbox/index.md), the Adobe Express Document API (from now on, Document API) is a powerful tool that extends the capabilities of Adobe Express add-ons, offering direct interaction with the open document. Let's take a moment to review the difference between the two core components of the architecture of an add-on.

-   The **iframe** hosts the add-on User Interface and runs its internal logic. You can think about it as a web application operating in a sandboxed environment: it needs to be separate from the rest of the Adobe Express content for security reasons, which is precisely why the add-on is hosted within an `<iframe>` element (a detailed technical description is found [here](/guides/develop/context.md#iframe-sandbox)). If you come from a CEP/UXP background, it's akin to developing the panel of an extension or plugin.
-   The **Document Model Sandbox**: allows you to operate on the document. It's a sandboxed JavaScript environment that communicates with the iframe (thanks to the [Communication API](/references/document-sandbox/communication/)), providing access to the [Document API](/references/document-sandbox/document-apis/). Drawing the parallel with CEP and UXP again, it represents scripting; that is, the possibility to drive Adobe Express programmatically and, for example, add pages or artboards, create new shapes, rotate or group them, etc.

This is a high-level overview of the overall structure; while the implementation has more technical nuances, there's no need to dive deeper now.

![](images/grids-addon-communication.png)

### The Project Structure

The complete code for the Grids System add-on can be found [here](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/express-grids-addon/): it is provided as a [complete project](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/express-grids-addon/grids-design-end), although it would be best if you followed along from [this starting point](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/express-grids-addon/grids-design-start), which sets up a JavaScript/Webpack environment with everything needed.[^1]

You can either clone the entire repository:

```bash
git clone https://github.com/AdobeDocs/express-add-on-samples.git
```

Or download it as a `.zip` file (click the green "Code" button and then "Download ZIP").

![](images/grids-addon-git.png)

Then `cd` in the project folder (either the `grids-design-start` or `grids-design-end` one) and run the following commands:

```bash
cd express-add-on-samples/document-sandbox-samples/express-grids-addon/grids-design-end

npm install
npm run build
npm run start
```

This will install the required dependencies, build the project, and then serve it locally on port 5241; if you need more clarification about how to load an add-on in Adobe Express, please refer to the [quickstart](/guides/getting_started/quickstart.md) guide for a step-by-step walkthrough.

Before jumping into the code, let's look at how the project is structured. At the time of this writing, the CLI provides a few templates, but Only ReactJS-based ones include the Document Sandbox while also having a Webpack configuration, which is preferable when using Spectrum Web Components (SWC). This project provides support for both of them.

![](images/grids-addon-folder-structure.png)

As usual, we'll work in the `src` folder while Webpack outputs the result in `dist`. The add-on entry point is `index.html`, which relies on `ui/index.js` for the iframe logic code (UI element handlers, etc.). The Document API entry point is instead `documentSandbox/code.js`, as defined in the `manifest.json`:

```json
{
    // ...
    "entryPoints": [
        {
            "type": "panel",
            "id": "panel1",
            "main": "index.html",
            "documentSandbox": "code.js" // 👈 here
        }
    ]
}
```

If you're wondering about `documentSandbox/shapeUtils.js`, it is an auxiliary file containing private code consumed by `code.js` that doesn't need to be exposed to the iframe in this specific project. The code of the blank template is as follows.

<!-- Code below -->
<CodeBlock slots="heading, code" repeat="4" languages="index.html, index.js, code.js, shapeUtils.js"/>

#### iframe

```html
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="description" content="Adobe Express Add-on tutorial using JavaScript and the Document Sandbox" />
        <meta name="keywords" content="Adobe, Express, Add-On, JavaScript, Document Sandbox, Document API" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Grids add-on</title>
        <link rel="stylesheet" href="styles.css" />
    </head>

    <body>
        <sp-theme scale="medium" color="light" theme="express">
            <sp-button id="createShape">Create shape</sp-button>
        </sp-theme>
    </body>
</html>
```

#### iframe

```js
// Spectrum imports
import "@spectrum-web-components/styles/typography.css";
import "@spectrum-web-components/theme/src/themes.js";
import "@spectrum-web-components/theme/theme-light.js";
import "@spectrum-web-components/theme/express/theme-light.js";
import "@spectrum-web-components/theme/express/scale-medium.js";
import "@spectrum-web-components/theme/sp-theme.js";
import "@spectrum-web-components/button/sp-button.js";

import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
    console.log("addOnUISdk is ready for use.");
    const createShapeButton = document.getElementById("createShape");

    // Get the UI runtime.
    const { runtime } = addOnUISdk.instance;
    const sandboxProxy = await runtime.apiProxy("documentSandbox");
    sandboxProxy.log("Document Sandbox up and running.");

    // Enabling CTA elements only when the addOnUISdk is ready
    createShapeButton.disabled = false;
});
```

#### Document API

```js
import addOnSandboxSdk from "add-on-sdk-document-sandbox";
const { runtime } = addOnSandboxSdk.instance;

function start() {
    runtime.exposeApi({
        log: (...args) => {
            console.log(...args);
        },
        // other properties will go here...
    });
}

start();
```

#### Document API

```js
// empty
```

<InlineAlert variant="info" slots="text1" />

Please use the iframe and Document API tabs above to switch between the two domains and find a dropdown in the top-right corner to select which file to show.

The `index.html` contains a `<sp-theme>` wrapper, whose role is explained [here](/guides/design/user_interface.md#spectrum-web-components-with-express-theme), and just a button. There's already something going on in `index.js` and `code.js` instead, which we must understand.

## The Communication API

A crucial component of any add-on that consumes the Document API is the communication bridge with the iframe. As we've seen earlier, it's precisely the role of the **Communication API**.

The mechanism is straightforward: through the `runtime` object (`code.js`, line 2), you can invoke the `exposeApi()` method, which grants the iframe access to the object literal that is passed as a parameter. The iframe must get to the `runtime`, too, and use its `apiProxy()` method passing `"documentSandbox"`. This asynchronous call results in the same object whose `log()` can now be invoked.

![Add-on Communication API](images/grids-addon-communicationapi.png)

It would not be uncommon to define an object literal first and pass it to the `exposeAPI` later.

<!-- code below -->
<!-- please note, the heading won't render anyway -->
<InlineAlert variant="warning" slots="heading, text1, text2, text3, text4" />

**Syntax**

Mind the syntax if you need the functions to call each other: for instance, the following won't work, as arrow functions' `this` is inherited from the enclosing scope, and there's none provided.

```js
runtime.exposeApi({
    log: (...args) => {
        console.log(...args);
    },
    createShape: (shape) => {
        // ...
        this.log("Shape created."); // ❌
    },
});
```

The _method shorthand syntax_ provides a proper `this` reference instead.

```js
runtime.exposeApi({
    log(...args) {
        console.log(...args);
    },
    createShape(shape) {
        // ...
        this.log("Shape created."); // ✅
    },
});
```

It's also possible to expose iframe methods to the Document Sandbox, i.e., using `apiProxy()` passing `"panel"`, but it's outside the scope of this tutorial—please refer to [this sample](/samples.md#communication-iframe-documentsandbox-sample) to see it in action.

## The Document API

### Using the Reference Documentation

The Document API is rapidly expanding: to keep track of its progress, you must get accustomed to consulting the [Reference Documentation](/references/document-sandbox/document-apis).

![Add-on Communication API](images/grids-addon-reference.png)

In the left-navbar, you can browse through all the Classes (which Adobe Express elements are instantiated from), Interfaces and constants. It's a hierarchical representation of the Document API data structures: for instance, you can see that a [`RectangleNode`](/references/document-sandbox/document-apis/classes/RectangleNode/) is a subclass of the [`FillableNode`](/references/document-sandbox/document-apis/classes/FillableNode/), which in turn subclasses the [`StrokableNode`](/references/document-sandbox/document-apis/classes/StrokableNode/), which eventually is just a particular kind of [`Node`](/references/document-sandbox/document-apis/classes/Node/)—the base class.

Some properties are shared among the `RectangleNode` and, say, other `StrokableNode` subclasses such as the `EllipseNode`: for instance, the `opacity`, or `blendMode`. Other ones are unique, like the `topLeftRadius`, which, in the context of an `EllipseNode`, wouldn't make sense.

### Creating the first Shape

It's finally time to start laying down some elements. Let's hook the only iframe button currently available to a function exposed by the Document API. Type the following into the source files (`index.html`, `index.js`, and `code.js` have been edited), then run the add-on.

<!-- Code below -->
<CodeBlock slots="heading, code" repeat="4" languages="index.html, index.js, code.js, shapeUtils.js"/>

#### iframe

```html
<body>
    <sp-theme scale="medium" color="light" theme="express">
        <sp-button id="createShape" disabled>Create shape</sp-button>
    </sp-theme>
</body>
```

#### iframe

```js
// ... usual imports

// Adding the sp-button import
import "@spectrum-web-components/button/sp-button.js";

addOnUISdk.ready.then(async () => {
    console.log("addOnUISdk is ready for use.");
    const createShapeButton = document.getElementById("createShape");

    const { runtime } = addOnUISdk.instance;
    const sandboxProxy = await runtime.apiProxy("documentSandbox");

    createShapeButton.addEventListener("click", async () => {
        sandboxProxy.createShape({ width: 200, height: 100 }); // 👈
    });

    createShapeButton.disabled = false;
});
```

#### Document API

```js
import addOnSandboxSdk from "add-on-sdk-document-sandbox";
const { runtime } = addOnSandboxSdk.instance;
import { editor, colorUtils, constants } from "express-document-sdk";

function start() {
    runtime.exposeApi({
        createShape({ width, height }) {
            // 👈
            const rect = editor.createRectangle();
            rect.width = width;
            rect.height = height;
            rect.translation = { x: 50, y: 50 };

            const col = colorUtils.fromRGB(0.9, 0.5, 0.9);
            const fillColor = editor.makeColorFill(col);
            rect.fill = fillColor;

            editor.context.insertionParent.children.append(rect);
        },
    });
}

start();
```

#### Document API

```js
// empty
```

Please note that it's considered good practice to initially **disable all interactive elements** that need to communicate with the Document API. In this case, there's only one CTA (Call To Action) `<sp-button>`, but generally any other elements that can make changes to the document should be treated similarly. You should enable them only when the `addOnUISdk` and `addOnSandboxSdk` are initialized, and event listeners are properly set (see `index.js` line 13).

The `createShapeButton` invokes the `createShape()` method defined and exposed in `code.js` (lines 7-19), passing an option object with arbitrary `width` and `height` properties. The function reveals key insights about the Document API—let's have a deeper look at the code.

According to the Reference, `createRectangle()` is a method of the [`Editor`](/references/document-sandbox/document-apis/classes/Editor/) class, which must be imported from `"express-document-sdk"` with the following statement.

```js
import { editor, colorUtils, constants } from "express-document-sdk";
```

We'll also make use of `colorUtils` and `constants`—they are named imports from `"express-document-sdk"`, too. The `createRectangle()` function doesn't need any parameter, either required or optional; hence, the properties of this new element must be set after its creation.

```js
const rect = editor.createRectangle();
rect.width = width;
rect.height = height;
rect.translation = { x: 50, y: 50 };
```

Dimensions and positions are straightforward while assigning a fill color is a two-step process.

```js
const col = colorUtils.fromRGB(0.9, 0.5, 0.9);
const fillColor = editor.makeColorFill(col);
rect.fill = fillColor;
```

First, you make use of the `fromRGB()` method from the `colorUtils` class, which expects four parameters in the (0..1) range: R, G, B and an optional Alpha, and returns a [Color](/references/document-sandbox/document-apis/classes/Color/) instance. Then, you use such color to create either a fill or stroke—here, we're using `makeColorFill()`. Finally, you set it to the shape by assigning it to the `fill` property.

<!-- code here -->
<InlineAlert variant="info" slots="text1" />

Strokes are created with the `editor.makeStroke()` method, which accepts more parameters (all optional). It's documented [here](/references/document-sandbox/document-apis/classes/Editor.md#makestroke).

The `rect` object now exists as a `RectangleNode` instance with a width of 200 pixels, a height of 100, the top-left corner at the coordinate (50, 50) and a pastel pink fill color. But **it still needs to be rendered on the page!**

```js
// appending the rect object to the scene
editor.context.insertionParent.children.append(rect);
```

Let's unpack this line. As it usually happens with any DOM (Document Object Model), it's easier if read _backwards_—from the end to the beginning. We are appending the `rect` object to the `children` list of the `insertionParent` (which is "the _preferred parent_ to insert newly added content into") of the `context` (the "User's current selection context"), a property of the `editor` class.[^2]

In other words, we're adding `rect` as a sibling of whatever happens to be active at the moment: this is what the `context.insertionParent.children` dance does. If you try to add `rect` while a shape nested inside a group is selected, then `rect` will also belong to that group. Please note that Adobe Express documents are based on data structures where instances are _appended_ to collections: you `append()` a rectangle to a container's `children` collection.[^3]

![](images/grids-addon-shape.png)

Alternatively, you can target the insertion point specifically rather than relying on what happens to be selected at the time of execution. For instance, the following code uses the first [Artboard](/references/document-sandbox/document-apis/classes/ArtboardNode/) of the first [Page](/references/document-sandbox/document-apis/classes/PageNode/).

```js
// ...
const doc = editor.documentRoot; // document
const currentPage = doc.pages.first; // page
const currentArtboard = currentPage.artboards.first; // artboard
currentArtboard.children.append(rect); // children
// or
editor.documentRoot.pages.first.artboards.first.children.append(rect);
```

Quoting a revealing bit of the Page reference:

> A PageNode represents a page in the document. A page contains one or more artboards, representing "scenes" in a linear timeline sequence. Those artboards, in turn, contain all the visual content of the document.

You now understand the fundamentals of the Adobe Express DOM and the hierarchical relations between nodes. You have all the necessary tools to begin coding the Grids add-on; you can always refer to the documentation when needed.

## Coding the Grids add-on

### Designing the UI with Spectrum Web Components

Although the main subject of this tutorial is the Document API, let's spend a moment discussing the Grid add-on's User Interface. It's built mainly with **Spectrum Web Components** (see [this guide](/guides/design/user_interface.md) for a refresher on Adobe's UX Guidelines and the use of the Spectrum Design System), in particular:

-   `<sp-number-field>` for the Rows and Columns inputs;
-   `<sp-slider>` for the Gutter;[^4]
-   `<sp-swatch>` for the color picker;
-   `<sp-button-group>` and `<sp-button>` for the CTA buttons.

The layout is based on nested FlexBox CSS classes, such as `row` and `column`. Because of the fixed width, margins are tight; the design has also been compacted along the Y-axis for consistency.

![](images/grids-addon-swc.png)

Please remember that any Spectrum Web Component you use must be installed and imported into the project first—refer to the instructions on [their official site](https://opensource.adobe.com/spectrum-web-components/) and [this guide](/guides/design/user_interface.md#spectrum-web-components-with-express-theme). In a nutshell, find the package name in each component's documentation, and then `npm install` the ones you need.

```bash
npm install @spectrum-web-components/button
npm install @spectrum-web-components/action-button
npm install @spectrum-web-components/button-group
npm install @spectrum-web-components/field-label
npm install @spectrum-web-components/number-field
npm install @spectrum-web-components/slider
npm install @spectrum-web-components/swatch
npm install @spectrum-web-components/theme
```

Finally, import them in the `ui/index.js` file.

```js
import "@spectrum-web-components/styles/typography.css";

import "@spectrum-web-components/theme/src/themes.js";
import "@spectrum-web-components/theme/theme-light.js";
import "@spectrum-web-components/theme/express/theme-light.js";
import "@spectrum-web-components/theme/express/scale-medium.js";
import "@spectrum-web-components/theme/sp-theme.js";

import "@spectrum-web-components/button/sp-button.js";
import "@spectrum-web-components/button-group/sp-button-group.js";
import "@spectrum-web-components/field-label/sp-field-label.js";
import "@spectrum-web-components/number-field/sp-number-field.js";
import "@spectrum-web-components/slider/sp-slider.js";
import "@spectrum-web-components/swatch/sp-swatch.js";
```

<InlineAlert variant="warning" slots="text1" />

Mind the import names: for example, you install a `@spectrum-web-components/button`, but you import it as `@spectrum-web-components/button/sp-button.js` (with the `sp-` prefix).

The only tricky UI bit worth mentioning here is relative to the **color pickers**. SWC features a variety of color-related components (Color Area, Color Handle, Color Loupe, Color Slider) but not an actual picker. This add-on implements it via a `<sp-swatch>` for the UI and a hidden native `<input>` element behind it.

<!-- Code below -->
<CodeBlock slots="heading, code" repeat="2" languages="index.html, ui/index.js"/>

#### index.html

```html
<div class="row">
    <!-- ... -->
    <sp-swatch id="rowsColorSwatch" class="color-well"></sp-swatch>
    <input type="color" id="rowsColorPicker" style="display: none;" />
</div>
```

#### ui/index.js

```js
// Ref to the <sp-input type="color">
const rowsColorPicker = document.getElementById("rowsColorPicker");
// Ref to the <sp-swatch>
const rowsColorSwatch = document.getElementById("rowsColorSwatch");

// Initializing the colors for both of them
rowsColorPicker.value = "#ccccff";
rowsColorSwatch.color = "#ccccff";

// The <sp-swatch> click triggers the <input> click
rowsColorSwatch.addEventListener("click", function () {
    rowsColorPicker.click();
});

// The <input> click changes the <sp-swatch> fill with the picked color.
rowsColorPicker.addEventListener("input", function (event) {
    const selectedColor = event.target.value;
    rowsColorSwatch.setAttribute("color", selectedColor);
});
```

The `<sp-swatch>` click handler programmatically triggers the `<input>` click, which, although hidden, can still display the browser's native color picker. On `input` (i.e., when the user selects a different color within the picker), the `color` attribute of the `<sp-swatch>` controlling its fill is changed accordingly to keep both of them in sync. Please note that their values are initialized in `ui/index.js` for convenience—setting them in `index.html` would be equally fine.

![](images/grids-addon-picker.png)

Please refer to the source code for other details on the HTML structure, which are not discussed here for brevity's sake.

### Collecting values from the UI

Let's finish the UI, completing the code for `ui/index.js`. As you can see, it is all standard JavaScript: besides the color pickers we've just discussed, Rows, Columns and Gutter values are initialized (lines 17-19); the Document Sandbox is retrieved, and everything the Document API exposes is stored in the `sandboxProxy` constant (lines 9-10).

<!-- Code below -->
<CodeBlock slots="heading, code" repeat="2" languages="index.html, ui/index.js"/>

#### index.html

```html
<body>
    <sp-theme scale="medium" color="light" theme="express">
        <h2>Design Grid creator</h2>
        <div class="row gap-20">
            <div class="row">
                <div class="column">
                    <sp-field-label for="rows" size="m">Rows</sp-field-label>
                    <sp-number-field id="rows" min="1" max="20"> </sp-number-field>
                </div>
                <sp-swatch id="rowsColorSwatch" class="color-well"></sp-swatch>
                <input type="color" id="rowsColorPicker" style="display: none;" />
            </div>
            <div class="row">
                <div class="column">
                    <sp-field-label for="cols" size="m">Columns</sp-field-label>
                    <sp-number-field id="cols" min="1" max="20"> </sp-number-field>
                </div>
                <sp-swatch id="colsColorSwatch" class="color-well"></sp-swatch>
                <input type="color" id="colsColorPicker" style="display: none;" />
            </div>
        </div>
        <div class="row">
            <sp-slider
                label="Gutter"
                id="gutter"
                variant="filled"
                editable
                hide-stepper
                min="1"
                max="50"
                format-options='{"style": "unit", "unit": "px"}'
                step="1"
            ></sp-slider>
        </div>
        <sp-button-group horizontal>
            <sp-button id="deleteGrid" variant="secondary" disabled>Delete</sp-button>
            <sp-button id="createGrid" disabled>Create</sp-button>
        </sp-button-group>
    </sp-theme>
</body>
```

#### ui/index.js

```js
// All the SWC imports...

import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
    console.log("addOnUISdk is ready for use.");

    // Get the Document Sandbox.
    const { runtime } = addOnUISdk.instance;
    const sandboxProxy = await runtime.apiProxy("documentSandbox");

    // Input fields -------------------------------------------

    const rowsInput = document.getElementById("rows");
    const colsInput = document.getElementById("cols");
    const gutterInput = document.getElementById("gutter");

    rowsInput.value = 4;
    colsInput.value = 6;
    gutterInput.value = 10;

    // Color pickers ------------------------------------------

    const colsColorPicker = document.getElementById("colsColorPicker");
    const colsColorSwatch = document.getElementById("colsColorSwatch");
    const rowsColorPicker = document.getElementById("rowsColorPicker");
    const rowsColorSwatch = document.getElementById("rowsColorSwatch");

    colsColorPicker.value = "#ffcccc";
    colsColorSwatch.color = "#ffcccc";
    rowsColorPicker.value = "#ccccff";
    rowsColorSwatch.color = "#ccccff";

    colsColorSwatch.addEventListener("click", function () {
        colsColorPicker.click();
    });
    colsColorPicker.addEventListener("input", function (event) {
        const selectedColor = event.target.value;
        colsColorSwatch.setAttribute("color", selectedColor);
    });

    rowsColorSwatch.addEventListener("click", function () {
        rowsColorPicker.click();
    });
    rowsColorPicker.addEventListener("input", function (event) {
        const selectedColor = event.target.value;
        rowsColorSwatch.setAttribute("color", selectedColor);
    });

    // CTA Buttons --------------------------------------------

    const createGridBtn = document.getElementById("createGrid");
    const deleteGridBtn = document.getElementById("deleteGrid");

    deleteGridBtn.onclick = async (event) => {
        const res = await sandboxProxy.deleteGrid();
        if (res) {
            // When there's been an error deleting the grid, you may want to handle it here
        }
        deleteGridBtn.disabled = true;
    };

    createGridBtn.onclick = async (event) => {
        await sandboxProxy.addGrid({
            columns: colsInput.value,
            rows: rowsInput.value,
            gutter: gutterInput.value,
            columnColor: colsColorPicker.value,
            rowColor: rowsColorPicker.value,
        });
        deleteGridBtn.disabled = false;
    };

    // Only now it is safe to enable the button
    createGridBtn.disabled = false;
});
```

Eventually, the two buttons (Delete and Create) invoke methods exposed by the Document API, respectively `deleteGrid()` and `createGrid()`. The latter expects an options object with `rows`, `columns`, `gutter`, `columnColor`, and `rowColor` properties.

### Validation and Error Handling

It's worth taking a moment to discuss good validation and error-handling practices at this stage. Just as the QA engineer walking into a bar in the [famous joke](https://twitter.com/brenankeller/status/1068615953989087232), you must ensure that user input aligns with what the grid algorithm expects; for example, that it receives unsigned integers.

For this tutorial, we'll limit ourselves to setting `min` and `max` values for the Rows, Columns, and Gutter ranges. This will prevent scenarios like creating a negative number of columns. In a typical implementation, you'd want to insert a validation routine before invoking the primary function. Depending on the algorithm's and the UI's complexity, this routine might belong to the iframe, the Document Sandbox, or both. Additionally, apart from validating value type and range, you may want to ensure that the Gutter size is compatible with the chosen number of Rows and Columns to prevent them from overflowing the page dimensions.[^5]

Another crucial notion is to avoid silent failures: every action should either succeed or provide the user with a notification if it doesn't. That's why, for instance, the Delete button is left disabled until a set of grids is created; instead of handling the removal of a non-existent grid, it's preferable to prevent it in the first place.

### Creating Rows and Columns

It makes sense to approach this grid business with some caution, as we're just starting with the Document API. Let's set up `documentSandbox/code.js` to expose this `addGrid()` method and manage the argument provided.

<!-- Code below -->
<CodeBlock slots="heading, code" repeat="1" languages="documentSandbox/code.js"/>

#### documentSandbox/code.js

```js
import addOnSandboxSdk from "add-on-sdk-document-sandbox";
const { runtime } = addOnSandboxSdk.instance;
import { editor, colorUtils, constants } from "express-document-sdk";

function start() {
    runtime.exposeApi({
        addGrid({ columns, rows, gutter, columnColor, rowColor }) {
            console.log("addGrid", columns, rows, gutter, columnColor, rowColor);
        },
    });
}

start();
```

When the user clicks the Create button, the parameters from the UI are properly collected, passed to `addGrid()` in the Document Sandbox, and logged. So far, so good, the Communication API does its job.

![](images/grids-addon-console.png)

To begin with, we'll create rows: rectangles that must be as wide as the page. To calculate their height, first, subtract the total number of gutters (which is equal to the number of rows plus one) from the page height. Then, divide the resulting value by the number of rows.

```text
rowHeight = (pageHeight - (rowsNumber + 1) * gutter) / rowsNumber;
```

This is because we're using gutters as page margins, too, as the following illustration shows.

![](images/grids-addon-rowheight.png)

We must get hold of the [Document](/references/document-sandbox/document-apis/classes/Editor.md#documentroot) (as `documentRoot`, from the Editor class) and [Page](/references/document-sandbox/document-apis/classes/PageNode/)—the first one from the `pages` list will be OK for our purposes. Page properties like `width` and `height` will be used to compute the attributes of each "row" Rectangle.

```js
// ...
runtime.exposeApi({
    addGrid({ columns, rows, gutter, columnColor, rowColor }) {
        const doc = editor.documentRoot;
        const page = doc.pages.first;
        const rowWidth = page.width;
        const rowHeight = (page.height - (rowsNumber + 1) * gutter) / rowsNumber;
    },
});
```

In case you want to use the currently active Page instead, you have to traverse back to it using the `insertionParent` property of the `context` we've seen earlier as a starting point, and its `parent` property until you reach a node whose `type` is equal to the string `"Page"`. Adobe Express documents must have at least one page, so this is a safe operation. Modify the `addGrid()` function as follows.

```js
addGrid({ columns, rows, gutter, columnColor, rowColor }) {
  // Using the current page.
  let currentNode = editor.context.insertionParent;
  let page = null;

  while (currentNode) {
    if (currentNode.type === "Page") {
      page = currentNode;
      break;
    }
    currentNode = currentNode.parent;
  }
// ... rest of the code
}
```

To draw all four (or any number coming from the UI) rectangles at once, a loop is in order.

```js
// ...
var rowsRect = [];
for (let i = 0; i < rows; i++) {
    let r = editor.createRectangle();
    r.width = page.width;
    r.height = rowHeight;
    // moving the row in place
    r.translation = { x: 0, y: gutter + (gutter + rowHeight) * i };
    rowsRect.push(r);
}
// adding the rows to the page
rowsRect.forEach((rect) => page.artboards.first.children.append(rect));
```

We've created all the needed rectangles, shifting them on the Y-axis according to their number and gutter, collecting them in a `rowsRect` array; which, in turn, we've looped through to append them all to the first `artboard` in the page.

<!-- code below -->
<InlineAlert variant="info" slots="text1" />

Please remember that you must always `append()` elements to their container's `children` property.

Using the same principles, we can create columns: rectangles as tall as the page and whose width we can compute.

```js
const doc = editor.documentRoot;
const page = doc.pages.first;
var colsRect = [];
const colWidth = (page.width - (cols + 1) * gutter) / cols;
for (let i = 0; i < cols; i++) {
    let r = editor.createRectangle();
    r.width = colWidth;
    r.height = page.height;
    r.translation = { x: gutter + (gutter + colWidth) * i, y: 0 };
    cols.push(r);
}
cols.forEach((rect) => page.artboards.first.children.append(rect));
```

We now have most of what is needed to complete the Grids add-on; we're in dire need of a better structure, though.

### Organizing the code

The Grid creation process can be split into **smaller, separate steps**—we can take this chance to think about how to structure the entire project.

-   Creating a rectangle is best handled using a dedicated `createRect()` function.
-   Rows and Columns can be separate processes, too.
-   `code.js` doesn't need to expose anything else but the `addGrid()` and `deleteGrid()` methods.
-   `addRows()` and `addColumns()` can belong to the `shapeUtils.js` module and imported in `documentSandbox/code.js`, while `createRect()` will be kept as private.

<!-- Code below -->
<CodeBlock slots="heading, code" repeat="2" languages="documentSandbox/code.js, documentSandbox/shapeUtils.js" />

#### documentSandbox/code.js

```js
import addOnSandboxSdk from "add-on-sdk-document-sandbox";
import { editor } from "express-document-sdk";
import { addColumns, addRows } from "./shapeUtils";

// Get the Document Sandbox.
const { runtime } = addOnSandboxSdk.instance;

function start() {
    const sandboxProxy = {
        addGrid({ columns, rows, gutter, columnColor, rowColor }) {
            addRows(rows, gutter, rowColor);
            addColumns(columns, gutter, columnColor);
            // ...
        },
        deleteGrid() {
            // ...
        },
    };
    runtime.exposeApi(sandboxProxy);
}
start();
```

#### documentSandbox/shapeUtils.js

```js
import { editor, colorUtils, constants } from "express-document-sdk";

// Utility to create a rectangle and fill it with a color.
const createRect = (width, height, color) => {
    const rect = editor.createRectangle();
    rect.width = width;
    rect.height = height;
    // Fill the rectangle with the color.
    const rectangleFill = editor.makeColorFill(colorUtils.fromHex(color));
    rect.fill = rectangleFill;
    return rect;
};

const addRows = (rowsNumber, gutter, color) => {
    const page = editor.documentRoot.pages.first;
    var rows = [];
    const rowHeight = (page.height - (rowsNumber + 1) * gutter) / rowsNumber;
    for (let i = 0; i < rowsNumber; i++) {
        let r = createRect(page.width, rowHeight, color);
        r.translation = { x: 0, y: gutter + (gutter + rowHeight) * i };
        rows.push(r);
    }
    rows.forEach((row) => page.artboards.first.children.append(row));
};

const addColumns = (columNumber, gutter, color) => {
    const page = editor.documentRoot.pages.first;
    var cols = [];
    const colWidth = (page.width - (columNumber + 1) * gutter) / columNumber;
    for (let i = 0; i < columNumber; i++) {
        let r = createRect(colWidth, page.height, color);
        r.translation = { x: gutter + (gutter + colWidth) * i, y: 0 };
        cols.push(r);
    }
    cols.forEach((col) => page.artboards.first.children.append(col));
};

export { addColumns, addRows };
```

As planned, `createRect()` conveniently acts as a rectangles factory function, consumed by `addRows()` and `addColumns()`. Since the color is received as a Hex string (like `"#ffcccc"`), we make use of the `colorUtil.fromHex()` method to convert into a Color instance—see `shapeUtils.js`, line 9.

It'd be nice to group rows and columns. The Editor class provides a [`createGroup()`](/references/document-sandbox/document-apis/classes/Editor.md#creategroup) method returning a [`GroupNode`](/references/document-sandbox/document-apis/classes/GroupNode/). Like all `ContainerNode` classes, it has a `children` property, which we can append rectangles to.

```js
const addRows = (rowsNumber, gutter, color) => {
    // ...
    var rows = [];
    // ...

    const rowsGroup = editor.createGroup(); // creating a group
    page.artboards.first.children.append(rowsGroup); // appending to the page
    rowsGroup.children.append(...rows); // appending rectangles
};
// 👆 same in addColumns()
```

![](images/grids-addon-groups.png)

To complete the project, we can add some finishing touches. Groups can be locked: preventing accidental shifts and transformations would be nice indeed. The Reference documentation comes in handy again with the boolean [`locked`](/references/document-sandbox/document-apis/classes/GroupNode.md#locked) property, which we can easily set after populating the group.

```js
// ...
rowsGroup.children.append(...rows);
rowsGroup.locked = true;
```

The Reference also shows an interesting [`blendMode`](/references/document-sandbox/document-apis/classes/GroupNode.md#blendmode): setting it to [`multiply`](/references/document-sandbox/document-apis/enumerations/BlendMode/#multiply) will produce a visually nicer overlay effect ([opacity](/references/document-sandbox/document-apis/classes/GroupNode.md#opacity) can be an alternative).

```js
// ...
rowsGroup.blendMode = constants.BlendMode.multiply;
rowsGroup.locked = true;
```

At present, the Reference includes only a few enumerations, such as `BlendMode`. As the Document API expands, more enumerations will be added. They provide sets of named constants, making the code more readable by replacing direct numeric values with descriptive names.

<InlineAlert variant="warning" slots="text1" />

For example, the Multiply blend mode corresponds to the number 3. Although, developers should avoid hard-coding enum's values, as they are for internal use and subject to change.

It would be preferable if a single group contained Rows and Columns; we must edit both `addRows()` and `addColumns()` first to return their group in order to reference them in the parent one.

```js
const addRows = (rowsNumber, gutter, color) => {
    // ...
    rowsGroup.locked = true;
    return rowsGroup; // 👈 returning the group
};

const addColumns = (columNumber, gutter, color) => {
    // ...
    columnsGroup.locked = true;
    return columnsGroup; // 👈
};
```

They can be referenced in `addGrid()`, appending them as children of this new group.

```js
addGrid({ columns, rows, gutter, columnColor, rowColor }) {
	// ...

	const rowGroup = addRows(rows, gutter, rowColor);
	const columnGroup = addColumns(columns, gutter, columnColor);

	// create a parent group
	const gridGroup = editor.createGroup();
	page.artboards.first.children.append(gridGroup);
	gridGroup.children.append(rowGroup, columnGroup); // filling with Rows and Columns
	gridGroup.locked = true;
}
```

### Deleting Grids

From the users' perspective, it would speed up the testing process of new grid designs if they could clear the current one and experiment with different combinations—that is, a Delete button. You can both add and remove elements to a container object's `children` list: most Node elements have a `removeFromParent()` method, which detaches them from their parent container.

```js
gridGroup.removeFromParent(); // voilà
```

Curb your enthusiasm: if you think about it, there might be an issue lurking here. The process of removing a group is performed at a later time, with respect to its creation: how can we be sure to target the correct container? Groups don't have names or IDs, at least for the time being. Luckily, the `code.js` file provides **an environment that persists in between iframe calls**: in other words, you can store the group in a variable and retrieve it later.

```js
let gridRef = null; // 👈 Grids group reference

function start() {
    runtime.exposeApi({
        addGrid({ columns, rows, gutter, columnColor, rowColor }) {
            // ...
            const gridGroup = editor.createGroup();
            // ...
            gridRef = gridGroup; // 👈 storing the group for later
        },
        deleteGrid() {
            if (gridRef) {
                try {
                    gridRef.removeFromParent(); // 👈 removing from the document
                    gridRef = null; //    clearing the reference
                } catch (error) {
                    console.error(error);
                    return "Error: the Grid could not be deleted.";
                }
            }
        },
    });
}
start();
```

Although not exposed through the Communication API, the `gridRef` variable is private to `code.js`, and exists within the closure of the functions defined inside and exposed by `runtime.exposeApi()`.[^6]

## Next Steps

Congratulations! You've coded from scratch the Grids Design System add-on. This proof-of-concept may be extended to make it even more useful as a product; you may implement the following features as an exercise.

-   **Page margins**: we're using the gutter for this purpose, but a proper `<sp-number-field>` can be added to allow users to set margins.
-   **Visibility toggle**: Use a `<sp-slider>`to control the grid's opacity, or add a `<sp-switch>` to toggle them on and off.
-   **Presets**: a dropdown menu might store commonly used grid sets—use a `<sp-picker>` and the [Client Storage API](/references/addonsdk/instance-clientStorage/).

## Lessons Learned

Let's review the concepts covered in this tutorial and how they've been implemented in the Grids add-on.

-   The **iframe** and the **Document Sandbox** are two distinct entities able to share contexts via the Communication API. We've used the `exposeApi()` method of the `runtime` object to allow the iframe to invoke functions in the Document API domain.
-   The **Document API** provides access to Adobe Express' Document Object Model, which defines containment structures and inheritance hierarchies. We've retrieved the document, its pages, and artboards; created, moved and assigned blending modes to shapes; created, populated and locked groups.
-   Nodes (elements) in Adobe Express documents can be added to the document in a position relative to the currently active selection or targeting a container as the **insertion point**; we've seen how `ContainerNode` elements have a `children` collection to `append()` elements to.
-   The Document API **context is permanent** in between iframe calls. We've seen that it's possible to store a reference to a Node within the exposed methods' closure and act upon it after its creation.
-   **Spectrum Web Components** are crucial to UI building, but sometimes they require customization; in this project, we've linked a `<sp-swatch>` to a traditional `<input>` element to create an Adobe Express' native-looking color picker.

## Final Project

The code for this project can be downloaded [here](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/express-grids-addon). It's available in two states: the starting point (one Create Shape button in the UI and the respective Document API function) if you want to follow along with the tutorial and type in the code—the best way to learn—and the final state, which code is also found below for convenience.

<!-- Code below -->
<CodeBlock slots="heading, code" repeat="5" languages="index.html, index.js, styles.css, code.js, shapeUtils.js" />

#### iframe

```html
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="description" content="Adobe Express Add-on tutorial using JavaScript and the Document Sandbox" />
        <meta
            name="keywords"
            content="Adobe, Express, Add-On, JavaScript, Document Sandbox, Adobe Express Document API"
        />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Grids add-on</title>
        <link rel="stylesheet" href="styles.css" />
    </head>

    <body>
        <sp-theme scale="medium" color="light" theme="express">
            <h2>Design Grid creator</h2>
            <div class="row gap-20">
                <div class="row">
                    <div class="column">
                        <sp-field-label for="rows" size="m">Rows</sp-field-label>
                        <sp-number-field id="rows" min="1" max="20"> </sp-number-field>
                    </div>
                    <sp-swatch id="rowsColorSwatch" class="color-well"></sp-swatch>
                    <input type="color" id="rowsColorPicker" style="display: none;" />
                </div>
                <div class="row">
                    <div class="column">
                        <sp-field-label for="cols" size="m">Columns</sp-field-label>
                        <sp-number-field id="cols" min="1" max="20"> </sp-number-field>
                    </div>
                    <sp-swatch id="colsColorSwatch" class="color-well"></sp-swatch>
                    <input type="color" id="colsColorPicker" style="display: none;" />
                </div>
            </div>
            <div class="row">
                <sp-slider
                    label="Gutter"
                    id="gutter"
                    variant="filled"
                    editable
                    hide-stepper
                    min="1"
                    max="50"
                    format-options='{"style": "unit", "unit": "px"}'
                    step="1"
                ></sp-slider>
            </div>
            <sp-button-group horizontal>
                <sp-button id="deleteGrid" variant="secondary" disabled>Delete</sp-button>
                <sp-button id="createGrid" disabled>Create</sp-button>
            </sp-button-group>
        </sp-theme>
    </body>
</html>
```

#### iframe

```js
import "@spectrum-web-components/styles/typography.css";

import "@spectrum-web-components/theme/src/themes.js";
import "@spectrum-web-components/theme/theme-light.js";
import "@spectrum-web-components/theme/express/theme-light.js";
import "@spectrum-web-components/theme/express/scale-medium.js";
import "@spectrum-web-components/theme/sp-theme.js";

import "@spectrum-web-components/button/sp-button.js";
import "@spectrum-web-components/button-group/sp-button-group.js";
import "@spectrum-web-components/field-label/sp-field-label.js";
import "@spectrum-web-components/number-field/sp-number-field.js";
import "@spectrum-web-components/slider/sp-slider.js";
import "@spectrum-web-components/swatch/sp-swatch.js";

import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
    console.log("addOnUISdk is ready for use.");

    // Get the Document Sandbox.
    const { runtime } = addOnUISdk.instance;
    const sandboxProxy = await runtime.apiProxy("documentSandbox");

    // Input fields -------------------------------------------

    const rowsInput = document.getElementById("rows");
    const colsInput = document.getElementById("cols");
    const gutterInput = document.getElementById("gutter");

    rowsInput.value = 4;
    colsInput.value = 6;
    gutterInput.value = 10;

    // Color pickers ------------------------------------------

    const colsColorPicker = document.getElementById("colsColorPicker");
    const colsColorSwatch = document.getElementById("colsColorSwatch");
    const rowsColorPicker = document.getElementById("rowsColorPicker");
    const rowsColorSwatch = document.getElementById("rowsColorSwatch");

    colsColorPicker.value = "#ffcccc";
    colsColorSwatch.color = "#ffcccc";
    rowsColorPicker.value = "#ccccff";
    rowsColorSwatch.color = "#ccccff";

    colsColorSwatch.addEventListener("click", function () {
        colsColorPicker.click();
    });
    colsColorPicker.addEventListener("input", function (event) {
        const selectedColor = event.target.value;
        colsColorSwatch.setAttribute("color", selectedColor);
    });

    rowsColorSwatch.addEventListener("click", function () {
        rowsColorPicker.click();
    });
    rowsColorPicker.addEventListener("input", function (event) {
        const selectedColor = event.target.value;
        rowsColorSwatch.setAttribute("color", selectedColor);
    });

    // CTA Buttons --------------------------------------------

    const createGridBtn = document.getElementById("createGrid");
    const deleteGridBtn = document.getElementById("deleteGrid");

    deleteGridBtn.onclick = async (event) => {
        const res = await sandboxProxy.deleteGrid();
        if (res) {
            // When there's been an error deleting the grid, you may want to handle it here
        }
        deleteGridBtn.disabled = true;
    };

    createGridBtn.onclick = async (event) => {
        await sandboxProxy.addGrid({
            columns: colsInput.value,
            rows: rowsInput.value,
            gutter: gutterInput.value,
            columnColor: colsColorPicker.value,
            rowColor: rowsColorPicker.value,
        });
        deleteGridBtn.disabled = false;
    };

    // Only now it is safe to enable the button
    createGridBtn.disabled = false;
});
```

#### iframe

```css
body {
    margin: 0;
    padding: 0;
    overflow-x: hidden;
}

sp-theme {
    margin: 0 var(--spectrum-global-dimension-static-size-300);
    display: grid;
}

.row {
    display: flex;
    flex-direction: row;
    justify-content: space-between;
    width: 100%;
    align-items: flex-end;
}

.gap-20 {
    gap: var(--spectrum-global-dimension-static-size-250);
}

.gutter-row {
    display: flex;
    flex-direction: row;
    justify-content: flex-end;
    width: 100%;
    align-items: flex-start;
    border: 1px solid black;
    margin-bottom: var(--spectrum-global-dimension-static-size-150);
}

.column {
    display: flex;
    flex-direction: column;
    padding-right: var(--spectrum-global-dimension-static-size-100);
    width: var(--spectrum-global-dimension-static-size-1000);
}

h2 {
    font-weight: var(--spectrum-global-font-weight-black);
}

sp-swatch {
    width: var(--spectrum-swatch-size-medium);
}

.color-well {
    cursor: pointer;
    --mod-swatch-border-thickness: var(--spectrum-divider-thickness-small);
    --mod-swatch-border-color: var(--spectrum-transparent-black-500);
}

sp-button {
    flex: 1;
    max-width: calc((100% - var(--spectrum-global-dimension-static-size-250)) / 2);
}

sp-number-field,
sp-slider {
    width: 100%;
}

sp-button-group {
    margin-top: var(--spectrum-global-dimension-static-size-300);
    width: 100%;
    display: flex;
    justify-content: space-between;
}
```

#### Document API

```js
import addOnSandboxSdk from "add-on-sdk-document-sandbox";
import { editor } from "express-document-sdk";
import { addColumns, addRows } from "./shapeUtils";

// Get the Document Sandbox.
const { runtime } = addOnSandboxSdk.instance;

let gridRef = null;

function start() {
    // APIs to be exposed to the UI runtime
    runtime.exposeApi({
        /**
         * Add a grid to the document.
         *
         * @param {Object} options - The options for the grid.
         * @param {number} options.columns - The number of columns in the grid.
         * @param {number} options.rows - The number of rows in the grid.
         * @param {number} options.gutter - The size of the gutter between columns and rows.
         * @param {string} options.columnColor - The color of the columns.
         * @param {string} options.rowColor - The color of the rows.
         * @returns {Group} The group containing the grid.
         */
        addGrid({ columns, rows, gutter, columnColor, rowColor }) {
            // Get the document and page.
            const doc = editor.documentRoot;
            const page = doc.pages.first;
            // Create the grid.
            const rowGroup = addRows(rows, gutter, rowColor);
            const columnGroup = addColumns(columns, gutter, columnColor);

            // Create the grid's group.
            const gridGroup = editor.createGroup();
            page.artboards.first.children.append(gridGroup);
            gridGroup.children.append(rowGroup, columnGroup);
            gridGroup.locked = true;

            // Save the grid reference.
            gridRef = gridGroup;
        },

        /**
         * Delete the grid from the document.
         * @returns {void}
         */
        deleteGrid() {
            if (gridRef) {
                try {
                    gridRef.removeFromParent();
                    gridRef = null;
                } catch (error) {
                    console.error(error);
                    return "Error: the Grid could not be deleted.";
                }
            }
        },
    });
}

start();
```

#### Document API

```js
import { editor, colorUtils, constants } from "express-document-sdk";

/**
 * Create a rectangle with the specified width, height, and color.
 * Private utility of the shapeUtils module.
 *
 * @param {number} width - The width of the rectangle.
 * @param {number} height - The height of the rectangle.
 * @param {string} color - The color of the rectangle in hex format.
 * @returns {RectangleNode} The created rectangle.
 */
const createRect = (width, height, color) => {
    const rect = editor.createRectangle();
    rect.width = width;
    rect.height = height;
    const rectangleFill = editor.makeColorFill(colorUtils.fromHex(color));
    rect.fill = rectangleFill;
    return rect;
};

/**
 * Add rows of rectangles to the document.
 *
 * @param {number} rowsNumber - The number of rows to add.
 * @param {number} gutter - The size of the gutter between rows.
 * @param {string} color - The color of the rows in hex format.
 * @returns {GroupNode} A group containing the created rows.
 */
const addRows = (rowsNumber, gutter, color) => {
    const doc = editor.documentRoot;
    const page = doc.pages.first;

    var rows = [];
    const rowHeight = (page.height - (rowsNumber + 1) * gutter) / rowsNumber;
    // Create the rectangles
    for (let i = 0; i < rowsNumber; i++) {
        let r = createRect(page.width, rowHeight, color);
        r.translation = { x: 0, y: gutter + (gutter + rowHeight) * i };
        rows.push(r);
    }
    // Append the rectangles to the document
    rows.forEach((row) => page.artboards.first.children.append(row));
    // Create the group
    const rowsGroup = editor.createGroup();
    // Append the group to the document
    page.artboards.first.children.append(rowsGroup);
    // Populate the group with the rectangles
    rowsGroup.children.append(...rows);
    // Edit the group's properties
    rowsGroup.blendMode = constants.BlendMode.multiply;
    rowsGroup.locked = true;
    return rowsGroup;
};

/**
 * Add columns of rectangles to the document.
 *
 * @param {number} columsNumber - The number of columns to add.
 * @param {number} gutter - The size of the gutter between columns.
 * @param {string} color - The color of the columns in hex format.
 * @returns {GroupNode} A group containing the created columns.
 */
const addColumns = (columsNumber, gutter, color) => {
    const doc = editor.documentRoot;
    const page = doc.pages.first;
    var cols = [];
    const colWidth = (page.width - (columsNumber + 1) * gutter) / columsNumber;
    // Create the rectangles
    for (let i = 0; i < columsNumber; i++) {
        let r = createRect(colWidth, page.height, color);
        r.translation = { x: gutter + (gutter + colWidth) * i, y: 0 };
        cols.push(r);
    }
    // Append the rectangles to the document
    cols.forEach((col) => page.artboards.first.children.append(col));
    // Create the group
    const columnsGroup = editor.createGroup();
    // Append the group to the document
    page.artboards.first.children.append(columnsGroup);
    // Populate the group with the rectangles
    columnsGroup.children.append(...cols);
    // Edit the group's properties
    columnsGroup.blendMode = constants.BlendMode.multiply;
    columnsGroup.locked = true;
    return columnsGroup;
};

export { addColumns, addRows };
```

<!-- Footnotes -->

[^1]: Alternatively, you can use this [blank template](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/express-addon-document-api-template) and start from scratch, but you'd need to manually add the `documentSandbox/shapeUtils.js` file and the various Spectrum imports.
[^2]: The quotes are from the Documentation Reference of each element.
[^3]: The terms "list" is used in the Adobe Express reference documentation, while "collection" may be more familiar to CEP/UXP developers; they are used interchangeably here.
[^4]: It could have been another `<sp-number-field>`, but a slider played well with the overall design.
[^5]: For example, you may want to retrieve the page's `width` and `height` properties at the beginning, and use them in the rest of the code.
[^6]: Future versions of the Document API may provide more deliberate ways to refer to elements.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extensibility
  - API
title: Adobe Express Add-on Tutorials
description: Adobe Express Add-on Tutorials covering the Adobe Express Add-on SDK and Document API
contributors:
  - https://github.com/hollyschinsky  
  - https://github.com/undavide
---

# Tutorials

In this page, you'll find a variety of tutorials covering the Adobe Express Add-on UI SDK and Document Sandbox APIs.

<ResourceCard slots="link, image, heading, text" width="50%"/>

[Express Document API](grids-addon.md)

![Grids add-on](images/thumbs-grids-addon.png)

### Creating a Grid System add-on with the Adobe Express Document API

Davide Barranca - November 6th, 2023

<ResourceCard slots="link, image, heading, text" width="50%"/>

[Coming Soon...](stats-addon.md)

![Coming Soon](images/thumbs-stats-addon.png)

### Creating a Stats add-on with the Adobe Express Communication API

Davide Barranca - December 14th, 2023

<ResourceCard slots="link, image, heading, text" width="80%"/>

[Express Document API](spectrum-workshop/index.md)

![Grids add-on](images/bingo-v1-addon.png)

### Building UIs using Adobe's Spectrum Design System

Holly Schinsky - January 25th, 2024
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Document API
  - Document Model Sandbox
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
title: Great UIs using Adobe's Spectrum Design System
description: This is an in-depth tutorial that will guide you in using Adobe's Spectrum Design System to help you build great UI's for your add-ons.
contributors:
  - https://github.com/hollyschinsky
---

# Building UIs using Adobe's Spectrum Design System

This tutorial will guide you on how to get started building great UI's for your add-ons using [Adobe Spectrum](https://spectrum.adobe.com/).

<InlineAlert slots="text" variant="success"/>

This tutorial was also presented in a recorded workshop that can be viewed [here](https://www.youtube.com/watch?v=5PA4KEN4JdQ).

## Introduction

In this tutorial, you will learn how to build two fully functioning [Adobe Express](https://new.express.adobe.com/) add-ons from scratch that use [Adobe Spectrum](https://spectrum.adobe.com/) for building the user interface. The concept for the add-on you will build is a bingo card generator, which allows a user to customize a bingo card with their chosen colors, random numbers and an optional FREE space.

The two different add-on's you will create are:

- A basic JavaScript add-on that uses [Spectrum Web Components](https://opensource.adobe.com/spectrum-web-components/) to build out the UI.

- A React-based add-on that uses the [`swc-react` Spectrum Web Components wrapper library](https://developer.adobe.com/express/add-ons/docs/guides/design/user_interface/#spectrum-web-components-with-react).

An example of what you will build is shown below:

![Bingo add-on screenshot](../images/bingo-v1-addon.png)

This add-on allows users to select settings to customize a bingo card; including background, foreground, title color, gridline size and whether to include a "FREE" space. The card is generated with random numbers, and ensures no numbers are used twice. The user can drag the customized card to the page, or click the "Add to page" button to use it in their document.

### Changelog

**February 6th, 2024**

- Updated tips on Spectrum CSS styling to add additional details on [why you should use Spectrum CSS variables](./part3.md#styling-with-spectrum-css) to style your add-ons, and [additional helpful guidelines for locating and using them](part3.md#layout-and-typography-styling)

**January 31st, 2024**

- First publication, by Holly Schinsky

### Prerequisites

- Familiarity with HTML, CSS, JavaScript.
- Familiarity with the Adobe Express add-ons environment; if you need a refresher, follow the [quickstart](/guides/getting_started/quickstart.md) guide.
- An Adobe Express account; use your existing Adobe ID or create one for free.
- Node.js version 16 or newer.

### Sample Projects

- [Lesson 1 project](https://github.com/hollyschinsky/bingo-card-generator-js) - Bingo Card Generator add-on using Spectrum Web Components and JavaScript

<!-- - The [lesson 2 starter project](https://github.com/hollyschinsky/bingo-card-generator-starter/blob/master/webpack.config.js)  -->

- [Lesson 2 project](https://github.com/hollyschinsky/bingo-card-generator-react-js) - Bingo Card Generator add-on using [swc-react](https://opensource.adobe.com/spectrum-web-components/using-swc-react/) and ReactJS

### Topics Covered

<ListBlock slots="text1, text2" repeat="2" iconColor="#2ac3a2" icon="disc" variant="fullWidth" />

[Configuring your add-on to use Spectrum Web Components](part1.md#create-and-configure-your-add-on)

[Using swc-react - Spectrum Web Component wrappers for React](part2.md#import-swc-react-components)

[Using Spectrum variables to customize the layout of your UI](part2.md#style-your-ui)

[Tips, Debugging & Troubleshooting](part3.md#troubleshooting-faq)

## Quickstart: Try Spectrum Web Components

A quick way to try out [Spectrum Web Components](https://opensource.adobe.com/spectrum-web-components/) without requiring any external tools, is to use a sandboxed environment like a codepen. See this [simple codepen](https://codepen.io/hollyschinsky/pen/xxBweyV), for example. It references the Spectrum Web Components libraries as bundles from a CDN for simplicity, and shows how to use the Express theme with a button component.

Check out [the codepen](https://codepen.io/hollyschinsky/pen/xxBweyV0), then try changing the `scale` value in the `<sp-theme>` tag to a value of `"large"` - then back to `"medium"` to see the effect.

**NOTE:** You can try using any other Spectrum Web Components in a similar fashion, ensuring they're included within the opening `<sp-theme>` and closing `</sp-theme>` tags.

Before moving on, check out [this codepen](https://codepen.io/hollyschinsky/pen/bGZrdoy) which implements the UI for the bingo card generator add-on and gives you a glimpse of what you're going to be building. You can change the layout to represent how it might look running in Express, by clicking the layout icon button outlined below, and dragging the width of the frame to 320px:

![Bingo codepen screenshot](../images/bingo-codepen.png)

<InlineAlert slots="text" variant="warning"/>

CDN URL references are used to show you a quick way to get started with Spectrum Web Components. However, you will notice the UI is laggy, so you wouldn't want to use this for your final add-on projects for performance reasons. In the following lessons, you will learn how to configure your projects to use only the modules and components your UI needs to ensure the best performance for your add-ons.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Document API
  - Document Model Sandbox
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
title: Great UIs using Adobe's Spectrum Design System
description: This is an in-depth tutorial that will guide you in using Adobe's Spectrum Design System to help you build great UI's for your add-ons.
contributors:
  - https://github.com/hollyschinsky
---

# Lesson 1: Use Spectrum Web Components in a basic JavaScript add-on

Configure and use Spectrum Web Components in a basic JavaScript add-on.

## Introduction

There are a few open source Spectrum libraries available, but we specifically recommend using the [Spectrum Web Components](https://opensource.adobe.com/spectrum-web-components) library, as it offers a comprehensive set of UI components with built-in benefits for developers, including:

- A built-in Express theme
- Accessibility
- Lightweight and performant
- Time savings due to the built-in styling
- Compliant with industry standards

## Steps

### Create and configure your add-on

Use the CLI to create a new add-on based on the basic `javascript` template:

```js
npx @adobe/create-ccweb-add-on bingo-card-generator-js --template javascript
```

<InlineAlert slots="text" variant="warning"/>

If you've used the CLI prior to this, you may want to run this command to ensure you have the most up-to-date version before creating your project --> `npx clear-npx-cache`

**NOTE:** You could use the CDN URL's once again to get started quickly, but since you'll want to ensure your add-on projects are performant, you will learn how to configure your local add-on project to use the specific Spectrum Web Components you'll need, instead.

If you run the project at this point (`npm run build; npm run start`), you will see a basic button displayed in the UI with custom CSS set to style it for Express, as shown below:

![Basic JS add-on screenshot](../images/basic-js.png)

However, since you're going to be implementing a whole new UI, go ahead and remove the existing lines related to the button:

Open the `src/index.html` file and **remove the following lines** within the `<body>` block:

```html
<div class="container">
    <button id="clickMe" disabled>Click me</button>
</div>
```

you should also **remove the associated CSS styles** from the `<style>` block since they are no longer needed:

```css
.container {
    margin: 24px;
    display: flex;
    flex-direction: column;
}

button {
    background-color: rgb(82, 88, 228);
    border-color: rgb(82, 88, 228);
    border-radius: 16px;
    border-style: solid;
    color: rgb(255, 255, 255);
    font-family: sans-serif;
    height: 32px;
}

button:disabled {
    background-color: rgb(177, 177, 177);
    border-color: rgb(177, 177, 177);
}

button:not([disabled]):hover {
    background-color: rgb(64, 70, 202);
    cursor: pointer;
}
```

Then, open the `src/index.js` and **remove the following lines**, (ensuring you keep the `addOnUISdk.ready.then(() => {...}` block intact).

```js
    const clickMeButton = document.getElementById("clickMe");
    clickMeButton.addEventListener("click", () => {
        clickMeButton.innerHTML = "Clicked";
    });

    // Enable the button only when:
    // 1. `addOnUISdk` is ready, and
    // 2. `click` event listener is registered.
    clickMeButton.disabled = false;
```

Next, you're going to need to configure your new add-on project to use webpack, since it's required to bundle the Spectrum Web Components properly. This requires a `webpack.config.js` file and some additional updates to your `package.json`:

1. First, create a new file named `webpack.config.js` in **the root** of your add-on project, (outside the `src`), and copy in the code block below (or, alternatively, copy it in from [the provided project](https://github.com/hollyschinsky/bingo-card-generator-starter/blob/master/webpack.config.js)):

    ```js
    const path = require("path");
    const HtmlWebpackPlugin = require("html-webpack-plugin");
    const CopyWebpackPlugin = require("copy-webpack-plugin");

    const isEnvProduction = process.env.NODE_ENV === "production";

    module.exports = {
        mode: isEnvProduction ? "production" : "development",
        devtool: isEnvProduction ? "source-map" : "eval-source-map",
        entry: "./src/index.js",
        experiments: {
            outputModule: true
        },
        output: {
            path: path.resolve(__dirname, "dist"),
            module: true,
            filename: "index.js"
        },
        externalsType: "module",
        externalsPresets: { web: true },
        plugins: [
            new HtmlWebpackPlugin({
                template: "src/index.html",
                scriptLoading: "module"
            }),
            new CopyWebpackPlugin({            
                patterns: [
                    { from: "src/*.json", to: "[name][ext]" },                
                    { from: "src/*.png", to: "[name][ext]", noErrorOnMissing: true },
                ],
            })
        ],
        module: {
            rules: [
                {
                    test: /\.(js)$/,
                    exclude: /node_modules/,
                    use: ["babel-loader"]
                },
                {
                    test: /(\.css)$/,
                    use: ["style-loader", "css-loader"]
                }
            ]
        },
        resolve: {
            extensions: [".js", ".css"]
        }
    };
    ```

2. Now, update your `package.json` to configure it to use webpack and add the required dependencies. This requires an update to the `scripts` block to add the `--use webpack` parameter, as shown below:

    ```json
     "scripts": {
        "clean": "ccweb-add-on-scripts clean",
        "build": "ccweb-add-on-scripts build --use webpack",
        "start": "ccweb-add-on-scripts start --use webpack",
        "package": "ccweb-add-on-scripts package --use webpack"
    }
    ```

    It will also require you to update your `devDependencies` block with the following:

    ```json
    "devDependencies": {
        "@adobe/ccweb-add-on-scripts": "^1.2.1",
        "@adobe/ccweb-add-on-sdk-types": "^1.2.1",
        "@babel/core": "7.23.3",
        "@babel/preset-env": "7.23.3",
        "@babel/preset-react": "7.23.3",
        "babel-loader": "9.1.3",
        "copy-webpack-plugin": "11.0.0",
        "css-loader": "6.8.1",
        "html-webpack-plugin": "5.5.3",
        "style-loader": "3.3.3",
        "webpack": "5.89.0",
        "webpack-cli": "5.1.4"
    }
    ```

    **IMPORTANT:** You will need to run `npm install` to ensure all of the new dependencies are installed.

### Set up the Express theme

1. Install and use the [Spectrum Web Components `<sp-theme>` component](https://opensource.adobe.com/spectrum-web-components/tools/theme/), which includes the modules that provide the overall theme for the Spectrum Web Components in your UI.

    `npm install @spectrum-web-components/theme@0.39.4`

    **Note:** if you prefer to use `yarn`, you could alternatively use the command: `yarn add @spectrum-web-components/theme@0.39.4`.

    Notice your new component is now included in the `package.json`.

1. Now, open your `src/index.js` and import the specific theme and typography classes below for the Express theme, color and scale you'll want to support in your add-on:

    ```js
    /* Theme and typography imports */
    import '@spectrum-web-components/styles/typography.css';
    import '@spectrum-web-components/theme/express/theme-light.js';
    import '@spectrum-web-components/theme/express/scale-medium.js';
    import '@spectrum-web-components/theme/sp-theme.js';    
    ```

    Optionally, note these theme-related imports to consider if you plan to include support for a future "dark" theme or "large" scale when add-ons are supported on mobile:

    ```js
    // import '@spectrum-web-components/theme/express/theme-dark.js'; /* to support a future dark theme */    
    // import '@spectrum-web-components/theme/express/scale-large.js'; /* future support for mobile for insance */
    ```

    **Note:** The `typography.css` import is not required, but is useful to note for using Spectrum CSS variables to help style the typography components of your add-ons, and to provide margins.

1. You can now add the `<sp-theme>` tag to your UI, but note that **you won't actually see anything visually yet**, since there are no components for it to be applied to. Open your `src/index.html` file, and add the following theme component into the `<body>` tags, configured with a `medium` scale, `light` color and `express` theme:

    ```html
    <sp-theme scale="medium" color="light" theme="express">
        <!-- UI content will go here -->
    </sp-theme>
    ```

    **NOTE:** Express currently only supports a light theme, but support for a dark theme will be coming in the future, so you could add some code that listens for the [Add-on UI SDK's `themechange` event](https://developer.adobe.com/express/add-ons/docs/guides/develop/use_cases/) and apply the change to your UI with something like the following:

    ```js
    addOnUISdk.app.on("themechange", (data) => { 
        applyTheme(data.theme); 
    });
    ```

    Another important thing to note, is the existence of the following block in the starter template `src/index.js` file, which can be used to ensure the Add-on UI SDK has been fully initialized and is ready for use before trying to implement your UI. You may have also noticed that the original button in the UI was set to `disabled`, and is subsequently enabled in this block:

    ```js
    addOnUISdk.ready.then(() => {        
        // Enable the button only when:
        // 1. `addOnUISdk` is ready, and
        // 2. `click` event listener is registered.
        clickMeButton.disabled = false;
    }
    ```

    Keep note of this pattern as you develop your own add-ons.

### Install Spectrum Web Components

Now you can start installing all of the Spectrum Web Components that will be used to build the UI of your add-on. These components are installed in a similar fashion to how the `<sp-theme>` component was added, with an `npm install` or `yarn add` command.

```bash
npm install @spectrum-web-components/button@0.39.4 @spectrum-web-components/button-group@0.39.4 @spectrum-web-components/field-label@0.39.4 @spectrum-web-components/menu@0.39.4 @spectrum-web-components/picker@0.39.4 @spectrum-web-components/slider@0.39.4 @spectrum-web-components/swatch@0.39.4 @spectrum-web-components/switch@0.39.4
```

**NOTE:** The above command specifies the `0.39.4` version specifically, due to an issue found with compatibility using the latest default version `0.40.3` as of this writing.

Alternatively, you could also copy in the following block below to the `dependencies` block of your `package.json` file, and then run `npm install` to install them all at once:

```json
"dependencies": {
    "@spectrum-web-components/button": "0.39.4",
    "@spectrum-web-components/button-group": "0.39.4",    
    "@spectrum-web-components/field-label": "0.39.4",
    "@spectrum-web-components/menu": "0.39.4",
    "@spectrum-web-components/picker": "0.39.4",
    "@spectrum-web-components/slider": "0.39.4",
    "@spectrum-web-components/swatch": "0.39.4",
    "@spectrum-web-components/switch": "0.39.4",            
    "@spectrum-web-components/theme": "0.39.4"        
}
```

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** You must ensure **the versions of all of your Spectrum Web Components installed are the same,** or you will see errors upon build or while running. You may want to just open your `package.json` file at this point to double check to ensure they all match, before moving on.

### Import Spectrum Web Components

Add the following list of imports for the new components into your `src/index.js` file with the following block:

```js
import "@spectrum-web-components/button/sp-button.js";
import "@spectrum-web-components/button-group/sp-button-group.js";
import "@spectrum-web-components/field-label/sp-field-label.js";
import '@spectrum-web-components/menu/sp-menu.js';
import '@spectrum-web-components/menu/sp-menu-item.js';
import "@spectrum-web-components/number-field/sp-number-field.js";
import '@spectrum-web-components/picker/sp-picker.js';
import "@spectrum-web-components/slider/sp-slider.js";
import "@spectrum-web-components/swatch/sp-swatch.js";
import '@spectrum-web-components/switch/sp-switch.js';
```

### Build UI with Spectrum Web Components

Next, open the `src/index.html` file and implement the following code for the UI components within the opening and closing `<sp-theme>` block, as provided below:

```html
<sp-theme scale="medium" color="light" theme="express">                
    <div class="row gap-20"> 
        <div class="column">
            <sp-field-label for="bgColorSwatch" size="m">Background color</sp-field-label>
            <sp-swatch id="bgColorSwatch" class="color-well"></sp-swatch>
            <input type="color" id="bgColorPicker" style="display: none;"/>                    
        </div>
        <div class="column">
            <sp-field-label for="fgColorSwatch" size="m">Number color</sp-field-label>
            <sp-swatch id="fgColorSwatch" class="color-well"></sp-swatch>
            <input type="color" id="fgColorPicker" style="display: none;"/>                    
        </div>                                                           
        <div class="column">
            <sp-field-label for="titleColorSwatch" size="m">Title color</sp-field-label>
            <sp-swatch id="titleColorSwatch" class="color-well"></sp-swatch>
            <input type="color" id="titleColorPicker" style="display: none;">                    
        </div>                        
    </div>  
    <div class="row gap-20 margin-top-10">  
        <div class="column">
            <sp-field-label for="fontWeightPicker">Font Weight</sp-field-label>
            <sp-picker id="fontWeightPicker" size="m" value="normal">
                <sp-menu-item value="normal">Normal</sp-menu-item>                        
                <sp-menu-item value="bold">Bold</sp-menu-item>                            
                <sp-menu-item value="lighter">Lighter</sp-menu-item>                
            </sp-picker>
        </div>     
        <div class="column gap-20">
            <sp-switch id="freeSpaceToggle" emphasized value="on" checked size="l">Free space</sp-switch>                               
        </div>                                                        
    </div>                   
    <div class="row gap-20">                    
        <sp-slider label="Gridlines width" id="gridlineSize" variant="filled" editable 
            hide-stepper min="1" max="10" value="5"
            format-options='{"style": "unit", "unit": "px"}' step="1">
        </sp-slider>
        <div class="column">
            <sp-field-label for="gridlinesColorSwatch" size="m">Color</sp-field-label>
            <sp-swatch id="gridlinesColorSwatch" class="color-well"></sp-swatch>
            <input type="color" id="gridlinesColorPicker" style="display: none;">                                            
        </div>
    </div> 
    <div class="margin-top-10">
        <sp-button-group horizontal>
            <sp-button id="generateBtn" disabled>Generate card</sp-button>
            <sp-button id="addBtn" variant="secondary" disabled>Add to page</sp-button>
        </sp-button-group>              
    </div>                
    <div class="margin-top-10">            
        <canvas id="finalCard"/>            
    </div>                            
</sp-theme>
```

Note the properties for each, and use the [Spectrum Web Component documentation](https://opensource.adobe.com/spectrum-web-components) to help cross-reference them for more context.

Worth mentioning, are the details around the use of the `<sp-swatch>` components, which are coupled with a hidden native `<input>` component to allow the user to pick their colors. Though SWC features a variety of color-related components (Color Area, Color Handle, Color Loupe, Color Slider), there is not an actual picker, so this add-on implements it via an `<sp-swatch>` for the UI and a hidden native `<input>` element behind it.

The `<sp-swatch>` click handler programmatically triggers the `<input>` click, which, although hidden, can still display the browser's native color picker. On input (i.e., when the user selects a different color within the picker), the `color` attribute of the `<sp-swatch>` updates as the color is changed to them in sync.

Also, be sure to check out [Adobe's UX Guidelines](https://xd.adobe.com/view/urn:aaid:sc:US:fd638450-1af8-49c3-ad29-0e76c2a2136f/) as many of these components are included with specific guidelines, including:

`<sp-number-field>` for the gridsize value
`<sp-slider>` for the gridsize picker
`<sp-swatch>` for the color pickers
`<sp-button-group>` and `<sp-button>` for the CTA buttons.

### Style your UI

If you run your add-on project with the CLI at this point (`npm run build; npm run start`), you will notice that your UI layout is less than ideal, as shown below:

![lesson 1 prestyle screenshot](../images/lesson1-prestyle.png)

Even though the Spectrum Web Components themselves have styling applied, the layout of them does not. That's because the Spectrum Web Components library doesn't include any specific layout components. However, you can use Spectrum CSS variables to help you with that.

In this step you will define some styles and selectors to improve the layout and general styling of your UI. You may have noticed there were already some classes set when you copied in the code block above, but since they don't actually apply yet, you'll eed to define them in this step.

Locate the `<style>` block in your `src/index.html`, and add the following CSS selectors and classes:

```css
sp-theme {
    margin: 0 var(--spectrum-global-dimension-static-size-100);
    display: grid;
}

h2 {
    font-weight: var(--spectrum-global-font-weight-black);
}

sp-swatch {
    width: var(--spectrum-swatch-size-medium);                
}

sp-button {
    flex: 1;
    max-width: calc(
        (100% - var(--spectrum-global-dimension-static-size-250)) / 2
    );
}

sp-textfield,
sp-picker {
    width: var(--spectrum-global-dimension-static-size-1700);
    display: flex;
}

sp-number-field {            
    width: 100%;
}

sp-button-group {
    margin-top: var(--spectrum-global-dimension-static-size-300);
    width: 100%;
    display: flex;
    justify-content: space-between;
}

sp-slider {
    width: 100%;                
    --spectrum-slider-font-size: var(--spectrum-font-size-100);
} 

sp-field-label {
    font-size: var(--spectrum-global-dimension-font-size-100);        
}

.color-well {
    cursor: pointer;
    --mod-swatch-border-thickness: var(--spectrum-divider-thickness-small);
    --mod-swatch-border-color: var(--spectrum-transparent-black-500);
}

.row {
    display: flex;
    flex-direction: row;
    justify-content: space-between;
    width: 100%;
    align-items: flex-end;
}

.column {
    display: flex;
    flex-direction: column;        
}

.gap-20 {
    gap: var(--spectrum-global-dimension-static-size-250); 
}

.margin-top-10 {
    margin-top: var(--spectrum-global-dimension-static-size-125); 
}

#bingoCanvas {
    width: 290px;       
} 
```

**TIP:** You can locate the custom global variables avaiable for use to adjust your UI as desired in the `/node_modules/@spectrum-web-components/styles/express/spectrum-core-global.css` of your project.

If you kept your add-on running in Express after the changes in the steps above, it should automatically refresh and you can view the updates. It should look something like this screenshot below:

![lesson 1 poststyle screenshot](../images/lesson1-poststyle.png)

### Wire UI code and add canvas drawing logic

After completing the above, you will see that many of the components aren't active yet, since there's currently no associated logic applied to set values or enable the buttons. First, continue adjusting the layout as needed, then, once you're happy with it, you can start implementing the logic to set some default values for the components and enable the **Generate card** button to allow the user to generate their customized bingo card. Open your `src/index.js` and copy in the following code snippet after your imports, replacing the `addOnUISdk.ready.then(() => {`  callback since it's included below.

```js
// Wait for the SDK to be ready
addOnUISdk.ready.then(() => {        
    console.log("addOnUISdk is ready for use.");    
    
    // Refs to the <sp-swatch> and <input> elements for each color
    const gridlinesColorSwatch = document.getElementById("gridlinesColorSwatch");
    const gridlinesColorPicker = document.getElementById("gridlinesColorPicker");
    
    const bgColorSwatch = document.getElementById("bgColorSwatch");        
    const bgColorPicker = document.getElementById("bgColorPicker");
    
    const fgColorSwatch = document.getElementById("fgColorSwatch");
    const fgColorPicker = document.getElementById("fgColorPicker");

    const titleColorSwatch = document.getElementById("titleColorSwatch");
    const titleColorPicker = document.getElementById("titleColorPicker");
    
    // Initialize colors for the above
    gridlinesColorPicker.value = "#5258e5"; // gridline color   
    gridlinesColorSwatch.color = "#5258e5"; // gridline color   
    bgColorPicker.value = "#f2f2f2";        // box background color
    bgColorSwatch.color = "#f2f2f2";        // box background color
    fgColorPicker.value = "#5258e5";        // bingo number color
    fgColorSwatch.color = "#5258e5";        // bingo number color
    titleColorPicker.value = "#000000";     // title color
    titleColorSwatch.color = "#000000";     // title color
  
    // Trigger click on the native color pickers for each
    gridlinesColorSwatch.addEventListener("click", function () {
        gridlinesColorPicker.click();
    });
  
    gridlinesColorPicker.addEventListener("input", function (event) {
      const selectedColor = event.target.value;
      gridlinesColorSwatch.setAttribute("color", selectedColor);
    });

    fgColorSwatch.addEventListener("click", function () {
        fgColorPicker.click();
    });

    fgColorPicker.addEventListener("input", function (event) {
        const selectedColor = event.target.value;
        fgColorSwatch.setAttribute("color", selectedColor);
    });
  
    bgColorSwatch.addEventListener("click", function () {
      bgColorPicker.click();
    });
  
    bgColorPicker.addEventListener("input", function (event) {
      const selectedColor = event.target.value;
      bgColorSwatch.setAttribute("color", selectedColor);
    });
  
    titleColorSwatch.addEventListener("click", function () {
        titleColorPicker.click();
    });
  
    titleColorPicker.addEventListener("input", function (event) {
      const selectedColor = event.target.value;
      titleColorSwatch.setAttribute("color", selectedColor);
    });
  
    // CTA button references
    const generateBtn = document.getElementById("generateBtn");  
    const addBtn = document.getElementById("addBtn");  
  
    // Generate button handler
    generateBtn.onclick = async (event) => {                    
      generateBingoCard();        
    };
  
    /* Enable the generate button now that the SDK is ready and the button event handler has been registered. The add to page button should only be enabled once a card has been generated. */
    generateBtn.disabled = false;        
});

// Function to generate the bingo card using an HTML canvas and drawing context 
function generateBingoCard() {
    const canvas = document.getElementById("finalCard");
    const ctx = canvas.getContext("2d");

    // Set canvas width and height
    canvas.width = 300;
    canvas.height = 360;

    // Set grid properties    
    let gridlineSize = document.getElementById("gridlineSize").value;        
    const numRows = 6;
    const numCols = 5;
    const cellWidth = 60;
    const cellHeight = 60;
    
    // Draw background rects with user selected color
    ctx.fillStyle = bgColorPicker.value; 
    for (let x = gridlineSize/2; x <= canvas.width; x += cellWidth-gridlineSize) {            
        for (let y = gridlineSize/2; y <= canvas.height; y += cellHeight-gridlineSize) {
            ctx.fillRect(x, y, cellWidth-gridlineSize, cellHeight-gridlineSize);                
        }
    } 
    
    // Draw gridlines
    ctx.lineWidth = gridlineSize;
    for (let i = 0; i <= numCols; i++) {        
        // Need to adjust for left/right gridlines size           
        ctx.moveTo(gridlineSize/2, 0);
        ctx.lineTo(gridlineSize/2, canvas.height);      

        ctx.moveTo(i * cellWidth-gridlineSize/2, 0);
        ctx.lineTo(i * cellWidth-gridlineSize/2, canvas.height);        
    }

    for (let i = 0; i <= numRows; i++) { 
        // Need to adjust for top/bottom gridlines size               
        ctx.moveTo(0, gridlineSize/2);
        ctx.lineTo(canvas.height, gridlineSize/2,);            
    
        ctx.moveTo(0, i * cellWidth-gridlineSize/2);
        ctx.lineTo(canvas.height, i * cellWidth-gridlineSize/2);                    
    }
    
    ctx.strokeStyle = gridlinesColorPicker.value;        
    ctx.stroke();
    
    // Draw bingo title
    ctx.font = fontWeightPicker.value +' 28px adobe clean';    
    ctx.textAlign = "center";
    ctx.textBaseline = 'middle'; 
    ctx.fillStyle = titleColorPicker.value; //font color                        
    let bingoTitle = ['B','I','N','G','O'];
    for (let charCnt = 0; charCnt < bingoTitle.length; charCnt++) {
        let letter = bingoTitle[charCnt];
        ctx.fillText(letter, charCnt * cellWidth + cellWidth / 2 - 4, cellHeight / 2 + 8);    
    }       
    
    // Generate random numbers
    const freeSpace = [3, 2]; // Coordinates of the FREE space
    const numbers = [];
    const usedNumbers = new Set(); // Track used numbers
    ctx.font = fontWeightPicker.value +' 22px adobe clean';
    ctx.fillStyle = fgColorPicker.value; // color of the numbers 
    ctx.textAlign = "center";
    const freeSpaceToggle = document.getElementById("freeSpaceToggle");
    
    for (let i = 1; i < numRows; i++) {
        numbers[i] = [];
        for (let j = 0; j < numCols; j++) {
            if (freeSpaceToggle.checked) {
                if (i === freeSpace[0] && j === freeSpace[1]) {
                    numbers[i][j] = "FREE";
                    continue; // Skip the FREE space
                }
            }
            let num;
            do {
                num = Math.floor(Math.random() * 15) + 1 + (j * 15);
            } while (usedNumbers.has(num)); // Generate unique numbers

            usedNumbers.add(num);
            numbers[i][j] = num;        
            ctx.fillText(num, j * cellWidth + cellWidth / 2 - 3, i * cellHeight + cellHeight / 2 + 3);
        }
    }

    // Draw "FREE" if the toggle is checked
    if (freeSpaceToggle.checked) {
        ctx.font = fontWeightPicker.value +' 20px adobe clean';     
        ctx.fillText("FREE", freeSpace[1] * cellWidth + cellWidth / 2 - 3, freeSpace[0] * cellHeight + cellHeight / 2 + 3);   
        ctx.drawImage(canvas, 0, 0);
    }    

    // Enable drag and drop for the card
    addOnUISdk.app.enableDragToDocument(canvas, {
        previewCallback: el => new URL(canvas.toDataURL()),
        completionCallback: async el => {
            const r = await fetch(canvas.toDataURL());
            const blob = await r.blob();
            return [{blob}];
        }
    })    
            
    // Add button click handler
    addBtn.onclick = async () => {      
        const r = await fetch(canvas.toDataURL());
        const blob = await r.blob();    
        addOnUISdk.app.document.addImage(blob);  
    }

    // Enable the add to page button    
    addBtn.disabled = false;
}
```

Once you've updated your code, your add-on should reload and you can generate a custom bingo card! Try playing with some settings and see how they render in a new card. You can also try to drag your card to the page, or add it with the add button etc. If your add-on didn't pick up the changes for any reason, you can always use the [add-on developer tools](https://opensource.adobe.com/spectrum-web-components/using-swc-react/) to do a refresh, or simply run `npm run build; npm run start` again.

![Bingo add-on screenshot](../images/bingo-v1-addon.png)

If you have any trouble, or don't see what you expect, see the [Troubleshooting section](./part3.md#troubleshooting-faq) of this tutorial for help. In the next lesson, we'll learn how to build the same add-on with a React and [**swc-react**](https://opensource.adobe.com/spectrum-web-components/using-swc-react/), Spectrum Web Component wrappers for React.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Document API
  - Document Model Sandbox
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
title: Great UIs using Adobe's Spectrum Design System
description: This is an in-depth tutorial that will guide you in using Adobe's Spectrum Design System to help you build great UI's for your add-ons.
contributors:
  - https://github.com/hollyschinsky
---

# Lesson 2: Use Spectrum Web Components in a React-based add-on

Learn how to configure and use Spectrum Web Components in a ReactJS add-on.

## Introduction

In this lesson, you will implement the bingo card generator add-on in a React-based project with a library called [**swc-react**](https://opensource.adobe.com/spectrum-web-components/using-swc-react/), a collection of wrapper components designed to make Spectrum Web Components (SWC) work like native React components in a React application. They serve as a bridge between React and Spectrum Web Components, and their properties and event names are directly derived from their corresponding SWC components. As such, the corresponding [Spectrum Web Components documentation](https://opensource.adobe.com/spectrum-web-components/) can be used as the documentation reference.

<InlineAlert slots="text" variant="info"/>

We recommend using **swc-react** over [**React Spectrum**](https://react-spectrum.adobe.com/react-spectrum/index.html) currently since the Spectrum Web Components library provides a more extensive set of components with an explicit Express theme that is continuously updated. React Spectrum’s Express theme is in alpha, doesn't have full component coverage, and is currently not being updated. Please note, however, that [a new version of Spectrum](https://s2.spectrum.adobe.com/) will be released sometime this year, and an update to the React Spectrum libraries will follow. In the meantime we recommend using the swc-react wrappersx.

## Steps

### Create project

1. Create a new project with the CLI based on the `react-javascript` template:

    `npx @adobe/create-ccweb-add-on bingo-card-generator-react --template react-javascript`

1. Open the project in your favorite code editor and navigate to the `src/components/App.jsx` file. Notice that it's preconfigured with the `@swc-react/theme` and `@swc-react/button` packages and their associated imports, with a basic usage. If you run the project at this point, you should see the button show up in your add-on:

    ![Basic react add-on screenshot](../images/react-starter.png)

    Take a moment to get familiar with what's included in the generated project before moving on. Notice it's pre-configured for webpack, so you don't have to do those configuration steps you had to do in lesson 1 for the basic JavaScript project.

### Install swc-react components

1. Next, start installing the UI components to your new add-on project for use. These components are installed in a similar fashion to how you installed the Spectrum Web Components to lesson 1, via `npm install` or `yarn add`, with just a change to the package prefix, from `@spectrum-web-components` to `@swc-react`. Remember, the **@swc-react/button** and **@swc-react/theme** components were already included in the project generated by the template, so you can skip those.

    ```bash
    npm install @swc-react/button-group@0.39.4 @swc-react/field-label@0.39.4 @swc-react/menu@0.39.4 @swc-react/picker@0.39.4 @swc-react/slider@0.39.4 @swc-react/swatch@0.39.4 @swc-react/switch@0.39.4
    ```

    **NOTE:** The above command specifies the `0.39.4` version specifically, due to an issue found with compatibility using the latest default version `0.40.3` as of this writing.

    Alternatively, replace the `dependencies` block in your `package.json` file with the following, and then run `npm install` to install them all at once:

    ```json
    "dependencies": {
            "@swc-react/button": "0.39.4",
            "@swc-react/button-group": "0.39.4",        
            "@swc-react/field-label": "0.39.4",
            "@swc-react/menu": "0.39.4",
            "@swc-react/picker": "0.39.4",
            "@swc-react/slider": "0.39.4",
            "@swc-react/swatch": "0.39.4",
            "@swc-react/switch": "0.39.4",        
            "@swc-react/theme": "0.39.4",
            "react": "18.2.0",
            "react-dom": "18.2.0"
    },    
    ```

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** You must ensure **the versions of all of the @swc-react component packages installed are the same,** or you will see errors upon build or while running. You can open your `package.json` file to double check to ensure they all match before moving on.

### Import swc-react components

In this step you will add the UI component imports for the bingo card generator add-on. The pattern of the imports will follow in a similar manner to what was included in the generated project for `Button` and `Theme`.

As a tip, you can use the [Spectrum Web Components Reference](https://opensource.adobe.com/spectrum-web-components/) for the corresponding component, and in the **Usage** section you will see that the third import uses the class name for the component, which is what you will need, as well as the specific package to use, it will just be prefixed with `@swc-react` instead.

So, for example, the first import is for the **Button Group** component. If you look at the [Spectrum Web Components - Button Group Usage](https://opensource.adobe.com/spectrum-web-components/components/button-group/#usage), the last import definition shows `import { ButtonGroup } from '@spectrum-web-components/button-group';`. It's outlined in the image below for visual reference:

![ButtonGroup import from SWC reference](../images/swc-button-group-import.png)

You can simply copy that import from the reference for any given component you want to use in your add-on, and just change the prefix from `@spectrum-web-components` to `@swc-react`. (Notice the existing imports for `Button` and `Theme`). The resulting import to use in your add-on would be:

`import { ButtonGroup } from '@swc-react/button-group';`.

You can then use this same pattern for all of the `@swc-react` wrapper components you want to use.

The imports needed for the bingo card generator add-on sample are listed below for you to copy into your `src/components/App.jsx` file, along with the existing `Button` and `Theme` imports:

```js
import { ButtonGroup } from '@swc-react/button-group';
import { FieldLabel } from '@swc-react/field-label';
import { MenuItem } from '@swc-react/menu';
import { Picker } from '@swc-react/picker';
import { Slider } from '@swc-react/slider';
import { Swatch } from '@swc-react/swatch';
import { Switch } from "@swc-react/switch";
```

### Create event helper class

Next you'll need to create a new class to handle a known issue where React events and web components don't always work well together.  See [this issue for more details](https://github.com/facebook/react/issues/19846). The issue is most often seen in the case of the React `onChange` event, and the events won't properly fire. An option to work around this is to create a helper class that will automatically register the native browser version of the events for the components to ensure they are properly fired.

Create a new file in your `src/components` folder and name it `WC.jsx`, then copy in the block of code below and save it.
  
**Note:** this class is also included in the [lesson 2 final project](https://github.com/hollyschinsky/bingo-card-generator-js-react) if you want to copy it in from there instead.

```js
import React from "react";

export class WC extends React.Component {
    constructor(props) {
        super(props);
        this.el = React.createRef();
        this.handleEvent = this.handleEvent.bind(this);
    }

    handleEvent(evt) {
        const propName = `on${evt.type[0].toUpperCase()}${evt.type.substr(1)}`;
        if (this.props[propName]) {
            this.props[propName].call(evt.target, evt);
        }
    }

    componentDidMount() {
        const el = this.el.current;
        const eventProps = Object.entries(this.props).filter(([k,v]) => k.startsWith("on"));
        eventProps.forEach(([k,v]) => el.addEventListener(k.substr(2).toLowerCase(), this.handleEvent));
    }

    componentWillUnmount() {
        const el = this.el.current;
        const eventProps = Object.entries(this.props).filter(([k,v]) => k.startsWith("on"));
        eventProps.forEach(([k,v]) => el.removeEventListener(k.substr(2).toLowerCase(), this.handleEvent));
    }

    render() {
        const filteredProps = Object.fromEntries(Object.entries(this.props).filter(([k,v]) => !k.startsWith("on")));
        return <div ref={this.el} {...filteredProps}>{this.props.children}</div>
    }
}
```

Now, go back into your `src/components/App.jsx` and import your new `WC` helper class under the `React` and `App.css` imports, for instance:

```js
import React, { useState, useRef } from "react";
import "./App.css";
import { WC } from "./WC.jsx";
```

### Build UI with swc-react components

At this point, you are ready to start using the `swc-react` components. You'll also wrap some with the `<WC>` helper class as needed to handle events appropriately. Open your `src/components/App.jsx` file and replace the current `<Theme>` block in the UI section with the following block:

```html
<Theme theme="express" scale="medium" color="light">
    <div className="container">
        <div className="row gap-20">             
            <div className="column">
                <FieldLabel size="l">Background color</FieldLabel>
                <WC onChange={onBgColorClick}>
                    <Swatch className="color-well" color={bgColorSwatch}></Swatch>
                </WC>
                <input ref={bgColorInput} type="color" style={{display: "none"}}
                    value={bgColor} onChange={onBgColorChange}
                />
            </div>
            <div className="column">
                <FieldLabel size="l">Number color</FieldLabel>
                <WC onChange={onFgColorClick}>
                    <Swatch className="color-well" color={fgColorSwatch}></Swatch>
                </WC>
                <input ref={fgColorInput} type="color" style={{display: "none"}}
                    value={fgColor} onChange={onFgColorChange}
                />                        
            </div>                                                       
            <div className="column">
                <FieldLabel size="l">Title color</FieldLabel>
                <WC onChange={onTitleColorClick}>
                    <Swatch className="color-well" color={titleColorSwatch}></Swatch>
                </WC>
                <input ref={titleColorInput} type="color" style={{display: "none"}}
                    value ={titleColor} onChange={onTitleColorChange}
                />                    
            </div>                                
        </div>
        <div className="row gap-20">
            <div className="column margin-top-10">
                <FieldLabel size="l">Font Weight</FieldLabel>
                <Picker size="m" value={fontWeightPicker} 
                    change={event => setFontWeightPicker(event.target.value)}>
                    <MenuItem value="normal">Normal</MenuItem>                        
                    <MenuItem value="bold">Bold</MenuItem>                            
                    <MenuItem value="lighter">Lighter</MenuItem>                
                </Picker>
            </div>  
            <div className="column">
                <WC onChange={event => setFreeSpaceToggle(event.target.checked)}>
                    <Switch emphasized checked={freeSpaceToggle} size="l">Free space</Switch>
                </WC>
            </div>         
        </div>
        <div className="row gap-20">                                
            <WC onChange={event => setGridlineSize(event.target.value)}>
                <Slider label="Gridlines size" variant="filled" editable value={gridlineSize}
                    hide-stepper min="1" max="10"
                    format-options='{"style": "unit", "unit": "px"}' step="1">
                </Slider>
            </WC>                                 
            <div className="column">
                <FieldLabel size="l">Color</FieldLabel>
                <WC onChange={onGridColorClick}>
                    <Swatch className="color-well" color={gridColorSwatch}></Swatch>
                </WC>
                <input ref={gridColorInput} type="color" style={{display: "none"}}
                    value={gridColor} onChange={onGridColorChange}
                />
            </div>                    
        </div>                 
        <div>
            <ButtonGroup horizontal>
                <Button onClick={generateBingoCard}>Generate card</Button>
                <Button onClick={handleAddToPage} disabled={!addToPageEnabled} variant="secondary">Add to page</Button>
            </ButtonGroup>              
        </div>                
        <div className="margin-top-10">                        
            <canvas ref={bingoCanvas}/>            
        </div> 
    </div>                                        
</Theme>
```

Note the use of the `<WC>..</WC>` component created in the previous step to wrap the `swc-react` components to ensure the events are are properly fired.

### Wire UI code and add canvas drawing logic

If you tried to run your add-on at this point, you would get a blank UI, and a check of the devtools console would reveal errors, since the UI components added above call functions that don't exist yet. So next you will add the logic to enable the UI components to work in your `src/components/App.jsx`. (In a typical project you would probably have more of a separation of concerns with your code rather that everything in the `App.jsx`, but for the purposes of this lesson, it will suffice).

Replace the current logic for the original button component in the top of the `App` class before the `return (...)` with the code below. You can also reference the [`App.jsx` file of the final project](https://github.com/hollyschinsky/bingo-card-generator-react-js/blob/master/src/components/App.jsx) for reference if you have any trouble:

```js
// State variables to hold component values
const [bgColor, setBgColor] = useState("#f2f2f2");
const [bgColorSwatch, setBgColorSwatch] = useState("#f2f2f2");

const [fgColor, setFgColor] = useState("#5258e5");
const [fgColorSwatch, setFgColorSwatch] = useState("#5258e5");

const [titleColor, setTitleColor] = useState("#000000");
const [titleColorSwatch, setTitleColorSwatch] = useState("#000000");

const [gridColor, setGridColor] = useState("#5258e5");
const [gridColorSwatch, setGridColorSwatch] = useState("#5258e5");

const [fontWeightPicker, setFontWeightPicker] = useState("normal");
const [freeSpaceToggle, setFreeSpaceToggle] = useState(true);
const [gridlineSize, setGridlineSize] = useState(5);
const [addToPageEnabled, setAddToPageEnabled] = useState(false);

// Refs to the UI elements for colors, add button and HTML canvas
const fgColorInput = useRef(null);
const bgColorInput = useRef(null);
const gridColorInput = useRef(null);
const titleColorInput = useRef(null);
const bingoCanvas = useRef(null);

// Function to generate the bingo card using an HTML canvas and drawing context 
function generateBingoCard() {              
    const ctx = bingoCanvas.current.getContext("2d");

    // Set canvas width and height
    bingoCanvas.current.width = 300;
    bingoCanvas.current.height = 360;
    
    // Set grid properties            
    const numRows = 6;
    const numCols = 5;
    const cellWidth = 60;
    const cellHeight = 60;
                    
    // Fill background boxes with selected bg color
    ctx.fillStyle = bgColor; 
    for (let x = gridlineSize/2; x <= bingoCanvas.current.width; x += cellWidth-gridlineSize) {            
        for (let y = gridlineSize/2; y <= bingoCanvas.current.height; y += cellHeight-gridlineSize) {
            ctx.fillRect(x, y, cellWidth, cellHeight);
        }
    }                        
            
    // Draw gridlines
    ctx.lineWidth = gridlineSize; 
    let x=0;
    let y=0;
    for (let i = 0; i <= numCols; i++) {        
        // Need to adjust for left/right gridlines size
        if (i===0) {
            ctx.moveTo(gridlineSize/2, 0);
            ctx.lineTo(gridlineSize/2, bingoCanvas.current.height);
        }
        else {
            ctx.moveTo(i * cellWidth-gridlineSize/2, 0);
            ctx.lineTo(i * cellWidth-gridlineSize/2, bingoCanvas.current.height);
            
        }
    }
    
    for (let i = 0; i <= numRows; i++) { 
        // Need to adjust for top/bottom gridlines size               
        if (i===0) {
            ctx.moveTo(0, gridlineSize/2);
            ctx.lineTo(bingoCanvas.current.height, gridlineSize/2,);
        }
        else {
            ctx.moveTo(0, i * cellWidth-gridlineSize/2);
            ctx.lineTo(bingoCanvas.current.height, i * cellWidth-gridlineSize/2);                    
        }                    
    }

    ctx.strokeStyle = gridColor; // Gridlines color
    ctx.stroke();                        
                        
    // Draw bingo title
    ctx.font = fontWeightPicker +' 28px adobe clean';    
    ctx.textAlign = "center";
    ctx.textBaseline = 'middle'; 
            
    ctx.fillStyle = titleColor; // title font color                       
    let bingoTitle = ['B','I','N','G','O'];
    for (let charCnt = 0; charCnt < bingoTitle.length; charCnt++) {
        let letter = bingoTitle[charCnt];
        ctx.fillText(letter, charCnt * cellWidth + cellWidth / 2, cellHeight / 2 + 6);                
    }       
    
    // Fill in the card with random numbers and a free space if checked
    const freeSpace = [3, 2]; // Coordinates of the FREE space
    const numbers = [];
    const usedNumbers = new Set(); // Track used numbers
    ctx.font = fontWeightPicker +' 22px adobe clean';
    ctx.fillStyle = fgColor; // color of the foreground (numbers)                 
            
    for (let i = 1; i < numRows; i++) {
        numbers[i] = [];
        for (let j = 0; j < numCols; j++) {
            if (freeSpaceToggle) {
                if (i === freeSpace[0] && j === freeSpace[1]) {
                    numbers[i][j] = "FREE";
                    continue; // Skip the FREE space
                }
            }

            let num;
            do {
                num = Math.floor(Math.random() * 15) + 1 + (j * 15);
            } while (usedNumbers.has(num)); // Generate unique numbers

            usedNumbers.add(num);
            numbers[i][j] = num;        
            ctx.fillText(num, j * cellWidth + cellWidth / 2 - 3, i * cellHeight + cellHeight / 2 + 3);                
        }
    }
            
    // Draw "FREE" if the toggle is checked
    if (freeSpaceToggle) {
        ctx.font = fontWeightPicker +' 20px adobe clean';     
        ctx.fillText("FREE", freeSpace[1] * cellWidth + cellWidth / 2 - 3, freeSpace[0] * cellHeight + cellHeight / 2 + 3);            
    }    
        
    // Enable drag and drop for the card
    addOnUISdk.app.enableDragToDocument(bingoCanvas.current, {
        previewCallback: el => new URL(bingoCanvas.current.toDataURL()),
        completionCallback: async el => {
            const r = await fetch(bingoCanvas.current.toDataURL());
            const blob = await r.blob();
            return [{blob}];
        }
    })        

    // Enable add card button
    setAddToPageEnabled(true);        
}

// Trigger click on the native color picker input for each
function onBgColorClick(e) {
    bgColorInput.current.click();
}

function onFgColorClick(e) {        
    fgColorInput.current.click();
}

function onTitleColorClick(e) {        
    titleColorInput.current.click();
}

function onGridColorClick(e) {        
    gridColorInput.current.click();
}

// Update the state values with the color selected from the native color picker for each
function onFgColorChange(e) {        
    setFgColorSwatch(e.target.value);
    setFgColor(e.target.value);        
}    

function onBgColorChange(e) {        
    setBgColorSwatch(e.target.value);
    setBgColor(e.target.value);        
}

function onTitleColorChange(e) {        
    setTitleColorSwatch(e.target.value);
    setTitleColor(e.target.value);        
}        

function onGridColorChange(e) {        
    setGridColorSwatch(e.target.value);
    setGridColor(e.target.value);        
}

async function handleAddToPage() {        
    const blob = await new Promise((resolve, reject) => {
        bingoCanvas.current.toBlob(blob => { resolve(blob); })
    })
    addOnUISdk.app.document.addImage(blob);            
}
```

**IMPORTANT!:**

Since you're using the React `useRef` to get references to some of the components, you'll need to add it to the import at the top of your `App.jsx`, along with the `useState` that's currently included. So the result of the import section would look like:

```js
import React, { useState, useRef } from "react"; /* add useRef here */
import "./App.css";                              /* already existed */
import { WC } from "./WC.jsx";                   /* you added in prior step */
```

### Style your UI

If you run your add-on project now with `npm run build; npm run start` (or if it was already running and automatically refreshed), you should see something like the following:

![Basic react add-on screenshot](../images/lesson2-prestyle.png)

Similar to lesson 1, you'll see that the layout of the UI is not great. In this step you'll add the styling to present the UI as you did in lesson 1.

Open the `/src/components/App.css` file and replace the current contents with the following custom type, class and id selectors for your UI, then check to see the updates reflected in your add-on before moving to the final part of the tutorial.

```css
sp-theme {
    display: grid;        
}

h2 {
    font-weight: var(--spectrum-global-font-weight-black);
}

sp-swatch {
    width: var(--spectrum-swatch-size-medium);                
}

sp-button {
    flex: 1;
    max-width: calc(
        (100% - var(--spectrum-global-dimension-static-size-250)) / 2
    );
}

sp-textfield,
sp-picker {
    width: var(--spectrum-global-dimension-static-size-1700);
    display: flex;
}

sp-number-field {            
    width: 100%;
}

sp-button-group {
    margin-top: var(--spectrum-global-dimension-static-size-300);
    width: 100%;
    display: flex;
    justify-content: space-between;
}

sp-slider {
    width: var(--spectrum-global-dimension-static-size-2800);
    --spectrum-slider-font-size: var(--spectrum-font-size-100);    
} 

sp-field-label {
   font-size: var(--spectrum-global-dimension-font-size-100);   
}

.color-well {
    cursor: pointer;
    --mod-swatch-border-thickness: var(--spectrum-divider-thickness-small);
    --mod-swatch-border-color: var(--spectrum-transparent-black-500);   
}

.row {
    display: flex;
    flex-direction: row;
    justify-content: space-between;
    width: 100%;
    align-items: flex-end;
}

.column {
    display: flex;
    flex-direction: column;    
}

.gap-20 {
    gap: var(--spectrum-global-dimension-static-size-250); 
}

.margin-top-10 {
    margin-top: var(--spectrum-global-dimension-static-size-125); 
}

#bingoCanvas {
    width: 290px;
}
```

<!-- TODO replace with final and more details about customizing -->
# Tips & Troubleshooting

Useful information to use while developing your add-on UI's with Spectrum.

## Tips

### Using icons

You can import and use an [icon from the Spectrum icon libraries](https://spectrum.adobe.com/page/icons/) provided in the [`icons-workflow`](https://opensource.adobe.com/spectrum-web-components/components/icons-workflow/) and [`icons-ui`](https://opensource.adobe.com/spectrum-web-components/components/icons-ui/) libraries.

- [**icons-workflow**](https://opensource.adobe.com/spectrum-web-components/components/icons-workflow/) - icons representing graphical metaphors such as a document, share symbol, trash can, etc.
- [**icons-ui**](https://opensource.adobe.com/spectrum-web-components/components/icons-ui/) - icons that are parts of a component definition like an X, magnifying glass or checkmark.

To use these icons, first add the associated library to your project by installing them from the command line, or via the `package.json`, then import them into your JS. For example:

```json
"@spectrum-web-components/icons-ui": "0.39.4",
"@spectrum-web-components/icons-workflow": "0.39.4",
```

Then import and use them; for instance:

```js
import "@spectrum-web-components/icons-workflow/icons/sp-icon-play-circle.js;"
import '@spectrum-web-components/icons-ui/icons/sp-icon-arrow75.js';
```

```html
<sp-icon-play-circle size="s"></sp-icon-play-circle>
<sp-icon-arrow75 size="m"></sp-icon-arrow75>    
```

**NOTE:** Icons adhere to the [Spectrum Design t-shirt sizing](https://spectrum.adobe.com/page/design-tokens/#Size-tokens), with a default of `size="m"` (for medium).

You can also use the [`[sp-icon]` package](https://opensource.adobe.com/spectrum-web-components/components/icon/) and specify an image directly via the `src` attribute, either with the image reference, or a data URL. Both are shown below for an example:

```html
<sp-icon src="icon-144x144.png"/>

<sp-icon
    size="l"
    label="Previous"
    src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9Ii0yOTU3Ljk5NSAtNTUzMC4wMzIgNiAxMCI+PGRlZnM+PHN0eWxlPi5he2ZpbGw6bm9uZTtzdHJva2U6IzE0NzNlNjtzdHJva2UtbGluZWNhcDpyb3VuZDtzdHJva2UtbGluZWpvaW46cm91bmQ7c3Ryb2tlLW1pdGVybGltaXQ6MTA7c3Ryb2tlLXdpZHRoOjJweDt9PC9zdHlsZT48L2RlZnM+PHBhdGggY2xhc3M9ImEiIGQ9Ik0yNTEuMywzMzNsNC00LTQtNCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoLTI3MDEuNjk1IC01MTk2LjAzMikgcm90YXRlKDE4MCkiLz48L3N2Zz4="
/>
```

You can also supply an `svg` to the `<sp-icon>` component, as shown below:

```html
<sp-icon>
    <svg
        xmlns="http://www.w3.org/2000/svg"
        viewBox="0 0 22 22"
        role="img"
        fill="currentColor"
        height="18"
        width="18"
        aria-hidden="true"
    >
        <path
            d="M19.75,10.04h-15l5.97-5.97a.483.483,0,0,0,0-.7l-.35-.36a.513.513,0,0,0-.71,0L2.24,10.44a.513.513,0,0,0,0,.71l7.39,7.84a.513.513,0,0,0,.71,0l.35-.35a.513.513,0,0,0,0-.71L4.76,11.5H19.75a.25.25,0,0,0,.25-.25v-.96A.25.25,0,0,0,19.75,10.04Z"
        ></path>
    </svg>
</sp-icon>                    
```

<InlineAlert slots="text" variant="warning"/>

Using an iconset reference from one of the `icons-workflow` or `icons-ui` packages in the `name` on an `sp-icon` should no longer be used (ie: `<sp-icon name="ui:Arrow100"></sp-icon>`), since it's deprecated. Use the specific named import mentioned in the first bullet above, instead.

### Spectrum sizing

In Spectrum, there are two main sizing concepts to understand:

- [**scale**](https://spectrum.adobe.com/page/platform-scale/) - the overall size of all of the components on the page, ie: medium for desktop, or large for touch, for instance.
- [**t-shirt sizes**](https://spectrum.adobe.com/page/design-tokens/#Size-tokens) - the size of a specific component, set as a variant or modifier to that component (ie: `size="m"`). **Note:** a component with a t-shirt sizing is still affected by `scale`.

### Fonts

There are a set of [Adobe Clean fonts](https://spectrum.adobe.com/page/fonts/) automatically injected by the [Add-on UI SDK](https://developer.adobe.com/express/add-ons/docs/references/addonsdk/#importing-the-addonuisdk-for-use) for use in your add-ons. You can see which are available by checking [the documentation](https://developer.adobe.com/express/add-ons/docs/guides/design/user_interface/#using-fonts). You can also see them while running an add-on via the browser developer tools, as shown in the following:

  ![Injected fonts screenshot](../images/fonts.png)

### Debugging

- Use the browser developer tools to inspect the HTML, and search for the `add-on-iframe-slot` element to find the add-on specific code container.
- From the developer tools, click into the variables in the stylesheets to see their values.
- Dig into the `node_modules/@spectrum-web-components` folder and view the component details to help better understand why an issue might be happening.
- Use the [API tab in the component reference](https://opensource.adobe.com/spectrum-web-components/components/slider/api/) or [the Storybook](https://opensource.adobe.com/spectrum-web-components/storybook) to locate the details around the supported events.

### Styling with Spectrum CSS

Use Spectrum CSS variables for padding, gaps between controls, and general layout. In addition, since Spectrum Web Components do not include any specific components for typography, you can also use variables to style the typography.

Some benefits to using Spectrum CSS variables to style your components over absolute values:

- By using Spectrum CSS global variables, you can ensure your UI aligns with the Spectrum design system, and if the design system changes, your UI will automatically update to the new design system.
- Using Spectrum CSS variables to style your UI allows you to easily update the styles across your entire application by simply updating the value of the variable. If you decide to change a color used throught your app, for example, you can update the value of a single Spectrum CSS variable, and all the elements that use that variable will be updated automatically.

#### Layout and typography styling

- [Layout](https://spectrum.adobe.com/page/design-tokens/#Layout-tokens) - the layout of your add-on can be adjusted by using global variables defined in the `@spectrum-web-components/styles/express/spectrum-core-global.css` folder in the `node_modules` of your add-on.

    **Some general guidelines** <br/>
    - `--spectrum-global-dimension-static-size-*` variables should be used when the dimension needs to be consistent across different elements or components, such as a uniform padding or margin throughout the application. It should also be used when a dimension needs to be adjusted based on a specific context, such as a container element or viewport size.

    - `--spectrum-global-static-size-*` variables should be used for values that are not necessarily consistent across the application, but need to be adjusted based on the content or use case. In general, these variables are typically used for text-related styles that may vary based on content or context.

    To summarize:
    - Use `--spectrum-global-dimension-static-size` variables for for dimensions such as `width`, `height`, `padding`, `margin`, or general spacing variables.
    - Use `--spectrum-global-static-size` variables for things like `font-size`, `line-height`, `border-radius`, etc.

- [Color variables](https://spectrum.adobe.com/page/color-fundamentals/) are provided as part of the `theme` imports. The color value’s contrast with the background increases as the value increases, so colors progressively get darker in a light theme, and lighter in a dark theme (ie: `--spectrum-global-color-purple-600` is *lighter* than `--spectrum-global-color-purple-900` in a `light` theme but *darker* in a `dark` theme). [Preview the color palette](https://spectrum.adobe.com/page/color-palette/) in the reference for more details.

    **TIP:** Use theme-specific color variables, such as those defined in the light theme for Express, located in the CSS files in your `@spectrum-web-components/styles/express/*` folder, for general uses of color in your add-on. For example, when the color will be applied to text, icons, or the borders of a component. Use *static* color variables defined in the overall `theme.js` when the color should be fixed and not dependent on the theme. The typical naming scheme is: `--spectrum-global-color-purple-600` and
    `--spectrum-global-color-static-purple-600`, respectively.

- [Typography](https://opensource.adobe.com/spectrum-css/typography.html) classes can be used to control your typography elements by importing the `typography.css`. For instance:

    ```html
    import "@spectrum-web-components/styles/typography.css";

     <div className="spectrum-Typography">  
        <p className="spectrum-Heading spectrum-Heading--sizeL">This is a custom large header text</p>
    </div>
    </h3>
    ```

    **Note:** by default, typography components do not include any outer margins, but adding the [`spectrum-Typography` class to your container](https://opensource.adobe.com/spectrum-css/typography.html#:~:text=Applying%20margins,will%20have%20the%20correct%20margins) will provide margins to the typography components within it. You can try out [this codepen](https://codepen.io/hollyschinsky/pen/eYXKpmj) to see an example of this, by removing the `spectrum-Typography` from the `div` and adding it back to see the difference in the margins. It also illustrates some of the typography classes for example usage.

- **Overriding variables:** you can override the Spectrum CSS variables as needed in your add-on as well, by setting the name of the spectrum variable to a new value, for instance:

    ```css
    --spectrum-global-dimension-font-size-150: 16px;
    ```

### Component modifier variables

Components have a set of variables defined to use for modifying properties specific to that particular component. They are prefixed with `--mod-*`, and should be used when you want to customize the styling of a specific component.

These variables are particularly useful in cases where you want to use a component in multiple places with different styles. By using custom variables, you can easily adjust the styling of a component in one place, and have those changes apply to all instances of the component throughout your application.

In the sample app, you used custom modifiers for a few of the components, including to modify the Slider font size, some Swatch  border properties and to adjust the Switch component, for reference.

A list of the prefixed custom properties for each UI component can be found in the Spectrum CSS repo's `mods.md` file for each component. For instance [the swatch component modifiers are listed here](https://github.com/adobe/spectrum-css/blob/main/components/swatch/metadata/mods.md), [and the slider component modifiers here](https://github.com/adobe/spectrum-css/tree/main/components/slider).

An example of their usage to modify the Slider is provided below for a reminder of what they look like:

```css
.color-well {                
    cursor: pointer;                
    --mod-swatch-border-thickness: var(--spectrum-divider-thickness-small);
    --mod-swatch-border-color: var(--spectrum-global-color-gray-200); 
}
```

## Troubleshooting

### Known issues

- [Spectrum Web Component version conflicts](https://opensource.adobe.com/spectrum-web-components/registry-conflicts/)

    You *must* use **matching component versions for all Spectrum Web Components (or swc-react components)** in your `package.json` or you will receive errors that are often not clear to determine the cause, so save yourself time and double check this if you're having issues running your add-on.

    This is mentioned in this tutorial a couple of times, but there is a known issue seen when using `@spectrum-web-components` (or `@swc-react`) packages with version `0.40.3`. At the moment `0.39.4` is a stable version that should work if you suspect a component version issue.

- [Picker](https://opensource.adobe.com/spectrum-web-components/components/picker/) flicker

    Currently there's a known issue with the `swc-react` **Picker** component in versions `0.36.*-0.40.*` where you will see the UI flicker when clicking it.

### Troubleshooting FAQ

This section is provided to help troubleshoot any errors you may encounter while following this tutorial.

- Why do I see registry errors in the console when running my add-on, for instance: `Uncaught DOMException: Failed to execute 'define' on 'CustomElementRegistry': the name "sp-icon-chevron100" has already been used with this registry` and `Base.dev.js:164 Attempted to redefine <sp-icon-chevron100>. This usually indicates that multiple versions of the same web component were loaded onto a single page. https://opensource.adobe.com/spectrum-web-components/registry-conflicts`

    This is probably due to mismatched versions of the `@spectrum-web-components` (or `@swc-react`) packages being used in your `package.json`. Don't forget to run `npm install` after updating your `package.json` to match the versions.

    **Solution:** open your `package.json` file and set all of the versions to the same one (ie: `0.39.4`). You can always reference [the sample projects](https://github.com/hollyschinsky/bingo-card-generator-js) as needed.

- Why do I see the following error when trying to build or start my add-on with the CLI? `ERROR in ./node_modules/@spectrum-web-components/button/src/Button.dev.js 145:6-78 Module not found: Error: Can't resolve '@spectrum-web-components/progress-circle/sp-progress-circle.js' in '/Users/hollyschinsky/spectrum-workshop-2023/workshop-projects/bingo-card-addon-react-start/node_modules/@spectrum-web-components/button/src' ... Field 'browser' doesn't contain a valid alias configuration resolve as module`

    **Solution:** there's a known issue seen when using `@spectrum-web-components` (or `@swc-react`) packages with version `0.40.3`, which is the latest version that are installed at the time of writing this tutorial, unfortunately. The solution is to update the versions of all components used in your `package.json` file to a known stable one like `0.39.4`. Don't forget to run `npm install` after updating to ensure the stable versions are installed before trying to build and run your add-on again.

- Is there a general solution to try when something doesn't work right with the CLI?

    **Solution:** try running `npx clear-npx-cache` to ensure the latest CLI version is installed, then run the CLI commands again.

- Why isn't the CLI building the output to the `dist` folder as I would expect? Did I forget to include a `webpack.config.js` file in the root of my project?

    **Solution:** make sure your [`webpack.config.js`](https://developer.adobe.com/express/add-ons/docs/guides/tutorials/spectrum-workshop/part1/#create-and-configure-your-add-on) is in the root of your project and not the `src` folder. You could also double check to ensure your project has the dependencies needed to use webpack. You could also try to replace your `package.json` file with the one from the [provided project](https://github.com/hollyschinsky/bingo-card-generator-react-js).

- I'm building a react-based add-on and it's not building correctly. Does the `scripts` object in the `package.json` of my add-on ensure the `--use webpack` parameter is used?

    **Solution:** ensure your `package.json` has the following `scripts` block. If it doesn't, it will not use webpack to build and start, package etc.

    ```json
    "scripts": {
        "clean": "ccweb-add-on-scripts clean",
        "build": "ccweb-add-on-scripts build --use webpack",
        "start": "ccweb-add-on-scripts start --use webpack",
        "package": "ccweb-add-on-scripts package --use webpack"
    }
    ```

- Are all of my components wrapped within an opening and closing `<sp-theme>` or `<Theme>` tag?

    **Solution:** make sure all your UI components are surrounded by the corresponding opening and closing theme tags for either Spectrum Web Components or `swc-react`, or you will not see the components rendered properly.

Still having issues? Ping me on [discord](https://discord.com/invite/nc3QDyFeb4) (username `hollyschinsky`) or email me at [hschinsk@adobe.com](mailto:hschinsk@adobe.com) for help.

## Resources

The following list of resources can be used to learn more about using Adobe's Spectrum Design System:

- Example codepens
    - [Simple button using Spectrum Web Components](https://codepen.io/hollyschinsky/pen/xxBweyV)
    - [Bingo Card Generator](https://codepen.io/hollyschinsky/pen/wvOyrLm)
    - [Spectrum Typography](https://codepen.io/hollyschinsky/pen/eYXKpmj)
    - [Spectrum CSS](https://codepen.io/lazd/pen/Exevvey)
- [Adobe Express UX Guidelines](https://xd.adobe.com/view/urn:aaid:sc:US:fd638450-1af8-49c3-ad29-0e76c2a2136f/)
- [Adobe Spectrum Storybook Web Components Storybook](https://opensource.adobe.com/spectrum-web-components/storybook/)
- [Adobe Spectrum Tokens Visualizer](https://opensource.adobe.com/spectrum-tokens/visualizer/)
- [Adobe Spectrum XD Plugin](https://spectrum.adobe.com/page/spectrum-xd-plugin/)
- [Adobe Spectrum Figma plugin](https://www.figma.com/community/file/1211274196563394418/adobe-spectrum-design-system)
- [Adobe Spectrum CDN Bundle](https://jspm.dev/@spectrum-web-components/bundle/elements.js/)
    - **Reminder:** you should only use this option for quick testing, but note that it will default to the Spectrum base theme unless you include the Express theme bundles specifically. See the [example codepens](https://codepen.io/hollyschinsky/pen/xxBweyV) for details.
- [Add-on Code Samples](https://developer.adobe.com/express/add-ons/docs/samples/)
- [Color Wheel](https://color.adobe.com/create/color-wheel)
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Document API
  - Express Communication API
  - Document Model Sandbox
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
title: Creating a Stats add-on with the Adobe Express Communication API
description: In this tutorial, we'll build an Adobe Express add-on that gathers statistics on the active document using the Communication API.
contributors:
  - https://github.com/undavide
---

# Creating a Document Stats add-on with the Adobe Express Communication API

In this tutorial, we'll build an Adobe Express add-on that gathers statistics on the active document using the Communication API.

## Introduction

Hello, and welcome to this Adobe Express Communication API tutorial, where we'll build together a **fully functional Stats add-on** from scratch. This add-on will retrieve metadata from the currently open Adobe Express document, such as pages and their size, plus information about the kind and number of any element used.

![](images/stats-addon.png)

### Timestamp

This tutorial has been written by Davide Barranca, software developer and author from Italy. It's been first published on December 14th, 2023.

### Prerequisites

- Familiarity with HTML, CSS, JavaScript.
- Familiarity with the Adobe Express add-ons environment; if you need a refresher, follow the [quickstart](/guides/getting_started/quickstart.md) guide.
- Familiarity with the Adobe Express Document API, covered in [this tutorial](grids-addon.md).
- An Adobe Express account; use your existing Adobe ID or create one for free.
- Node.js version 16 or newer.

### Topics Covered

<!-- List block here -->
<ListBlock slots="text1, text2" repeat="2" iconColor="#2ac3a2" icon="disc" variant="fullWidth" />

[Invoking Document Model Sandbox methods from the UI iframe](#proxy-api)

[Invoking UI iframe methods from the Document Model Sandbox](#logic)

[Proxy API](#proxy-api)

[Context Closures](#functions)

![](images/stats-addon-animation.gif)

## Getting Started with the Communication API

As we've seen in the previous Adobe Express [Document API tutorial](grids-addon.md), add-ons belong to the **UI iframe**: a sandboxed environment subject to [CORS policies](../develop/context.md#cors), where the User Interface (UI) and the add-on logic are built. The iframe itself has limited editing capabilities, though: via the `addOnUISdk` module, it can invoke a few methods to import media (image, video, and audio) and export the document into a number of formats, like `.pdf`, `.mp4` or `.jpg` for example.

The **Document API** makes new, more powerful capabilities available, allowing the add-on to manipulate elements directly—like scripting in Desktop applications such as Photoshop or InDesign. This API is one component of the Document Sandbox, a JavaScript execution environment that also includes a restricted set of Web API (mostly debugging aids) as well as the means for the UI iframe and the Document API to exchange messages—the Communication API. This infrastructure is paramount as it bridges the gap between the two environments, allowing them to create a seamless experience.

### Proxies

How does this all work, then? The process involves exposing proxies for the *other context* to use, serving as a user-friendly abstraction; under the hood, the implementation relies on a messaging system, which is hidden to us developers.

```js
// runtime in the UI iframe
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
const { runtime } = addOnUISdk.instance;

// runtime in the Document Sandbox
import addOnSandboxSdk from "add-on-sdk-document-sandbox";
const { runtime } = addOnSandboxSdk.instance;
```

The `runtime` object uses the `exposeApi()`to make content available to the other context—it works the same, regardless of whether the subject is the iframe or the Document Sandbox.

```js
// 👇 both in the UI frame and the Document Sandbox
runtime.exposeApi({ /* ... */ }); // exposing a payload {}
```

We'll get to the details of such a payload in a short while; for the moment, think about it as a collection of methods acting on their environment (UI iframe or Document Sandbox). There needs to be more than exposing, though: some action is required *on the other side* to surface such a payload—it involves using the `apiProxy()` method documented [here](/references/addonsdk/instance-runtime/).

```js
// UI iframe, importing a payload from the Document Sandbox
const sandboxProxy = await runtime.apiProxy("documentSandbox");

// Document Sandbox, importing a payload from the UI iframe
const panelUIProxy = await runtime.apiProxy("panel");
```

At this point, `sandboxProxy` and `panelUIProxy` represent their counterparts from the original contexts. It all may be easier to understand when the entire process is written down; for example, in the following code, we expose a custom method called `ready()` defined in the UI iframe to the Document API.

<CodeBlock slots="heading, code" repeat="2" languages="UI iframe, Document Sandbox"/>

#### UI iframe

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
const { runtime } = addOnUISdk.instance;

// exporting a payload to the Document Sandbox
runtime.exposeApi({ 
  ready: (env) => {
    console.log(`The ${env} environment is ready`);
  }
});
```

#### Document Sandbox

```js
import addOnSandboxSdk from "add-on-sdk-document-sandbox";
const { runtime } = addOnSandboxSdk.instance;

// importing from the iframe
const panelUIProxy = await runtime.apiProxy("panel"); 

// We can call this method now
await panelUIProxy.ready("Document Sandbox");
```

As the name implies, the `panelUIProxy` constant in the Document Sandbox is a *proxy* for the object exposed by the iframe's runtime. The other way around works the same: exposing a Document API method to the iframe.

<CodeBlock slots="heading, code" repeat="2" languages="iframe, Document Sandbox"/>

#### UI iframe

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
const { runtime } = addOnUISdk.instance;

// importing from the Document Sandbox
const sandboxProxy = await runtime.apiProxy("documentSandbox");

// We can call this method now
await sandboxProxy.drawRect();
```

#### Document Sandbox

```js
import addOnSandboxSdk from "add-on-sdk-document-sandbox";
const { runtime } = addOnSandboxSdk.instance;

// exporting a payload to the iframe
runtime.exposeApi({ 
  drawRect: () => {
    // uss the Document API to draw a Rectangle shape...
  }
});
```

The following diagram helps visualize the process.

![Proxy objects](images/stats-addon-proxy.png)

### Proxy API

Now that we've seen how contexts expose and import each other's API, let's discuss what's inside the payload objects that cross this environment boundary.

#### Functions

Most of the time, you're going to expose **functions**.

```js
// Document Sandbox
runtime.exposeApi({
  drawRect:    () => { /* ... */ }, // 👈
  drawEllipse: () => { /* ... */ }, // 👈
  drawShape:   () => { /* ... */ }, // 👈
  // etc.
});
```

In the above example, if `drawShape()` needs to call either `drawEllipse()` or `drawRect()`, you may use the *method shorthand syntax*.

```js
// Document Sandbox
runtime.exposeApi({
  drawRect()    { /* ... */ }, // 👈
  drawEllipse() { /* ... */ }, // 👈
  drawShape() { 
    this.drawRect();           // 👆
    // or
    this.drawEllipse();        // 👆
  },
  // etc.
});
```

When not strictly necessary, keep functions private and expose only the ones needed.

```js
// Document Sandbox
const drawRect    = () => { /* ... */ };  // 👈 private
const drawEllipse = () => { /* ... */ };  // 👈 private

runtime.exposeApi({
  drawShape() { 
    drawRect();    // 👆
    // or
    drawEllipse(); // 👆
  }
});
```

Here, `drawRect()` and `drawEllipse()` exist within the closure of the `drawShape()` function exposed to the iframe and will work just fine when the iframe invokes it. This notion of "private" variables defined in one context can be exploited in various ways, for instance, with a counter as follows.

<CodeBlock slots="heading, code" repeat="2" languages="iframe, Document Sandbox"/>

#### UI iframe

```js
const sandboxProxy = await runtime.apiProxy("documentSandbox");

// Calling the exposed method
const shapesNo = await sandboxProxy.drawShape();
console.log("Shapes drawn", shapesNo);
```

#### Document Sandbox

```js
const drawRect    = () => { /* ... */ };
const drawEllipse = () => { /* ... */ };

let counter = 0;    // 👈 private to the sandbox

runtime.exposeApi({
  drawShape() { 
    if (counter >= 10) { throw new Error("Shape's budget depleted!"); }
    // Randomly draw either a rectangle or an ellipse
    Math.random() < 0.5 ? drawRect() : drawEllipse();

	return ++counter; // 👆
  }
});
```

The `counter` variable in the Document Sandbox is maintained between iframe calls within the same user session. It remains isolated to the specific document and cannot be shared with other open documents or users. However, it can be accessed by the `drawShape()` function. In this context, it's returned to provide the iframe with the count of shapes created up to that point. This introduces us to the notion of **returned values**.

Generally speaking, you should restrict your returns to the following types.

- ✅ Primitive values.
- ✅ Object literals.
- ✅ JSON strings.
- ✅ ArrayBuffers and Blobs.
- ✅ Promises.

The following returns won't work as expected and must be avoided.

- ❌ Classes (constructor functions).
- ❌ Class instances (will get serialized and stripped away from any method).
- ❌ Functions.
- ❌ Proxies.
- ❌ Constructs such as `Maps` and `Sets` won't get through either, nor will `Date` and `RegExp`.
- ❌ `new Error()`, either thrown or returned, won't provide any error message (at the moment) when caught using a `try`/`catch` block.

#### Primitives

Nothing prevents you from using something else besides functions in your proxy. For instance, you can refactor the `drawShape()` example by exposing a `counter` property alongside its setter and getter.

<CodeBlock slots="heading, code" repeat="2" languages="iframe, Document Sandbox"/>

#### UI iframe

```js
// iframe
const sandboxProxy = await runtime.apiProxy("documentSandbox");

for (let i = 0; i < 10; i++) {
  await sandboxProxy.drawShape();
}
sandboxProxy.counter = 0; // resetting the counter
await sandboxProxy.drawShape();
```

#### Document Sandbox

```js
// Document Sandbox
const drawRect    = () => { /* ... */ };
const drawEllipse = () => { /* ... */ };

let _counter = 0; 👈 // private member (mind the underscore)

runtime.exposeApi({
  drawShape() { 
    if (_counter >= 10) { // 👈 mind the underscore
      throw new Error("Shape's budget depleted!");
    }
    // Randomly draw either a rectangle or an ellipse
    Math.random() < 0.5 ? drawRect() : drawEllipse();
	this.counter = this.counter + 1; // Use the setter to increment 
	return this.counter; // Return the new value after incrementing
  },
  get counter()    { return _counter; }, // 👈 getter
  set counter(val) { _counter = val; }   // 👈 setter
});
```

The `counter` setter has the ability to perform additional actions, such as manipulating the document, in addition to assigning a new value to the private variable `_counter`.

Please note that, given the async nature of the Communication API, retrieving the `counter` value in the iframe requires the use of `await` or a `then()` callback.

```js
let counter = await sandboxProxy.counter;
// or
sandboxProxy.counter.then((counter) => { /* ... */ });
```

### Asynchronous communication

The Communication API wraps all inter-context function invocations with a **Promise**. In other words, regardless of the nature of the function called, when it gets from one context to the other (from the iframe to the Document Sandbox or vice-versa), it must be dealt with as if it were **asynchronous**.

```js
// Document Sandbox
runtime.exposeApi({
  drawShape() { /* ... */ } // 👈 Document API methods are typically *synchronous*
});

// iframe
❌ const res = sandboxProxy.drawShape(); // 👀 no await, returns a Promise
❌ console.log(res instanceof Promise);  // true

✅ const res = await sandboxProxy.drawShape(); // using await
✅ console.log(typeof res); // number (it returns the counter, as you remember)
```

## Coding the Stats add-on

You are now equipped with all the theory and reference snippets needed to start building the Stats add-on: it's a simple project implementing the Communication API in a couple of different ways. Feature-wise, it's split into two parts.

1. The add-on shows two **status lights** that indicate whether the SDKs are ready for use.
1. At the press of a button, the add-on (via Document API) collects the document's metadata[^0], which is used to compile and show a **table of Nodes** (elements).

![](images/stats-addon-vscode.png)

Like in the [Grids add-on tutorial](grids-addon.md), the starting point will be [this template](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/express-addon-document-api-template), which provides a Webpack-managed JavaScript—hence, able to easily import Spectrum Web Components to build the User Interface. Everything's in the `src` folder:

- `index.html` is where the iframe's UI is built.
- `ui/index.js` deals with the add-on's internal logic.
- `ui/table-utils.js` contains table-related functions consumed by the iframe and imported by `index.js` to keep it slim.
- `documentSandbox/code.js` contains the Document API methods exposed to the iframe.
- `documentSandbox/utils.js` stores Document API private functions imported in `code.js`.

### User Interface

To keep a consistent look & feel with the rest of the application, we'll use Spectrum Web Component as much as possible, styling them with the `express` theme provided by the `<sp-theme>` wrapper.

![](images/stats-addon-doc.png)

For the "Framework Status", the [Status Light](https://opensource.adobe.com/spectrum-web-components/components/status-light/) component is spot-on: it comes in many variants, which set different light colors—`positive` and `negative` (green 🟢 and red 🔴) will be enough for us. The "Document Statistics" section is going to show a list of key/value pairs (the element type and the number of items found on each page). The most obvious choice is a [Table](https://opensource.adobe.com/spectrum-web-components/components/table/) component, which in SWC is constructed with several tags.

- `<sp-table>` is the outer wrapper.
- `<sp-table-head>` and `<sp-table-head-cell>` set the header.
- `<sp-table-body>` is for the body, which contains `<sp-table-row>` and `<sp-table-cell>` elements.

We'll start with a placeholder row with a friendly message, which is going to be removed at the first launch. A regular `<sp-button>` is placed at the bottom to initiate the metadata-collecting process.

<CodeBlock slots="heading, code" repeat="1" languages="index.html"/>

#### index.html

```html
<body>
  <sp-theme scale="medium" color="light" theme="express">
    <h3>Framework status</h3>
    <hr>
    <div class="row">
      <sp-status-light size="m" variant="negative" id="iframe-status">
        iFrame API
      </sp-status-light>
      <sp-status-light size="m" variant="negative" id="document-status">
        Authoring API
      </sp-status-light>
    </div>
    <h3>Document statistics</h3>
    <hr>
    <div class="row">
      <sp-table size="m">
        <sp-table-head>
          <sp-table-head-cell>Element</sp-table-head-cell>
          <sp-table-head-cell>Count</sp-table-head-cell>
        </sp-table-head>
        <sp-table-body id="stats-table-body">
          <sp-table-row id="row-placeholder">
            <sp-table-cell>Get the Document stats first...</sp-table-cell>
          </sp-table-row>
        </sp-table-body>
      </sp-table>
    </div>
    <div class="row align-right">
      <sp-button id="stats">Analyze document</sp-button>
    </div>
  </sp-theme>
</body>
```

### Logic

The diagram below illustrates the communication flow between the two contexts.

![](images/stats-addon-flow.png)

The iframe exposes two methods:

- `toggleStatus()` will be used independently by the iframe and the Document API to switch the Framework Status lights to green when ready.
- `createTable()` expects to be passed the document metadata and deals with the `<sp-table>` setup.

The Document Sandbox exposes only a `getDocumentData()` method, which collects the metadata from the open document. Both contexts import each other's API via proxy.

When the iframe has loaded its SDK, it will call `toggleStatus()`, passing the `"iframe"` string as a parameter—telling the function which light to turn green. Similarly, when the Document Sandbox is ready, it will reach out for `toggleStatus()` on its own. Neither process requires the user's intervention.

When the "Analyze Document" button is clicked, the iframe—via the Document Sandbox proxy—invokes `getDocumentData()`. Instead of returning an object with the metadata to the iframe for further processing (which would be OK), **the Document API uses the iframe proxy to run directly** `createTable()` and initiate the table subroutine in an *iframe-to-Document-Sandbox-to-iframe* roundtrip. Let's have a look at the overall structure in `index.js` implementing the logic I've just described.

<CodeBlock slots="heading, code" repeat="1" languages="index.js"/>

#### ui/index.js

```js
// SWC imports
import "@spectrum-web-components/styles/typography.css";
import "@spectrum-web-components/theme/src/themes.js";
import "@spectrum-web-components/theme/theme-light.js";
import "@spectrum-web-components/theme/express/theme-light.js";
import "@spectrum-web-components/theme/express/scale-medium.js";
import "@spectrum-web-components/theme/sp-theme.js";

import "@spectrum-web-components/status-light/sp-status-light.js";
import "@spectrum-web-components/table/elements.js";
import "@spectrum-web-components/button/sp-button.js";

import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Wait until the addOnUISdk has been loaded
addOnUISdk.ready.then(async () => {
  // API to expose to the Document Sandbox
  const iframeApi = { 
    createTable(documentData) { /* ... */ },
    toggleStatus(sdk) { /* ... */ }
  };
  runtime.exposeApi(iframeApi);
  
  // Toggle the iframe SDK status light
  iframeApi.toggleStatus("iframe");
  
  // Import the Document Sandbox API proxy
  const { runtime } = addOnUISdk.instance;
  const sandboxProxy = await runtime.apiProxy("documentSandbox");
  // Exposing the iFrame API to the Document Sandbox.
  
  // Set the button's click handler
  const statsButton = document.getElementById("stats");
  statsButton.addEventListener("click", async () => {
    // Invoke the Document API via Document Sandbox proxy
    // to get the document metadata and initiate the table creation process
    await sandboxProxy.getDocumentData(); // 👈 mind the await
  });

  // Enable the button only when the addOnUISdk is ready
  statsButton.disabled = false;
});
```

Besides the usual SWC imports, everything must be wrapped by a callback invoked when the `addOnUISdk` module is `ready`—which also means we can switch the first SDK status light to green. Please note that `toggleStatus()` must be available to both the iframe and the Document Sandbox: declaring the `iframeApi` constant first (lines 18-21) and passing it to `exposeApi()` later allows me to call it (line 21).

```js
// ❌ _in this case_ it's the wrong syntax choice!
runtime.exposeApi({ 
  createTable(documentData) { /* ... */ },
  toggleStatus(sdk) { /* ... */ }
});

// ✅ better for our needs _in this context_
const iframeApi = { 
  createTable(documentData) { /* ... */ },
  toggleStatus(sdk) { /* ... */ }
});
runtime.exposeApi(iframeApi);
// toggleStatus is accessible in the iframe too
iframeApi.toggleStatus("iframe"); // 👈
```

<InlineAlert variant="info" slots="text" />

Let me remind you again of the need to `await` when invoking `getDocumentData()` (line 37, `index.js`), as the Communication API wraps proxy calls with Promises.

In `documentSandbox/code.js`, we bring the iframe proxy in, toggle the status light, and expose the `getDocumentData()` function. Please note that it must be declared asynchronous (line 7) because of the need to `await` when invoking the `panelUIProxy` method `createTable()` (line 12).

<CodeBlock slots="heading, code" repeat="1" languages="code.js"/>

#### documentSandbox/code.js

```js
import addOnSandboxSdk from "add-on-sdk-document-sandbox";
const { runtime } = addOnSandboxSdk.instance;

async function start() {
  const panelUIProxy = await runtime.apiProxy("panel");
  runtime.exposeApi({
    async getDocumentData() {                    // 👈 async keyword, because 👇
      // Get the document's metadata
      let documentData;
      // ... TODO
      // ... then, directly invoke the iframe method
      await panelUIProxy.createTable(documentData); // 👈 the Communication API is async 👆
    }
  });
  // switch the Framework Status light to green
  panelUIProxy.toggleStatus("document");
}
start();
```

<InlineAlert variant="info" slots="text, text1, text2" />

Please note that it would be perfectly fine to return the `documentData` object to the iframe and let it invoke `createTable()` on its own. I've chosen to do it this way to show you how that this sort of "circular" communication is possible—although the other approach is perhaps more common.

Speaking of coding style in the way the proxy is exposed, you may find more readable to implement the functions elsewhere (either in the same file or in a separate module) and use the object property shorthand syntax.

```js
const getDocumentData = async () => { /* ... */ };
// ...
runtime.exposeApi({
  getDocumentData, // 👈 shorthand syntax
  // ...
});
```

### Implementation

Let's start filling in the missing parts in our code; we'll begin with the Framework Status, the easiest bit. The `toggleStatus()` method is immediately invoked in the `addOnUISdk.ready` callback, as well as the Document Sandbox `code.js`, where it is also exposed. It updates the `variant` attribute of the `<sp-status-light>` element based on the `sdk` parameter passed in.

<CodeBlock slots="heading, code" repeat="2" languages="iframe, Document Sandbox"/>

#### UI iframe

```js
const iframeApi = {
  toggleStatus(sdk) {
  // sdk parameter validation  
	if (["document", "iframe"].indexOf(sdk) === -1) {
	  throw new Error("Invalid SDK type");
	}
	const el =
	  sdk === "document"
		  ? document.getElementById("document-status")
		  : document.getElementById("iframe-status");
	el.setAttribute("variant", "positive"); // 🟢
  },
  // ...
}

iframeApi.toggleStatus("iframe"); // 👈
```

#### Document Sandbox

```js
import addOnSandboxSdk from "add-on-sdk-document-sandbox";
const { runtime } = addOnSandboxSdk.instance;

async function start() {
  const panelUIProxy = await runtime.apiProxy("panel");
  // ...
  panelUIProxy.toggleStatus("document"); // 👈
}
start();
```

When refreshing the add-on, the UI updates almost instantly, but a frame-by-frame analysis would reveal a progression in the rendering process: first, the HTML is loaded, then the CSS with the `<sp-status-light>` components in their original, "red" variant; finally, when the two SDK are fully loaded, we get the green lights.[^1]

![Status lights](images/stats-addon-lights.png)

Let's tackle the metadata collection in the Document Sandbox, especially the data structure we want to create[^2]. There are many ways to go about this business: I've decided to keep track of elements on a Page basis and store page dimensions, too. Eventually, the iframe will receive `documentData`, an array of objects, one for each page,  with `dimensions` and `nodes` properties. If you've got a taste for TypeScript, the type definition would be as follows.

```ts
type DocumentData = Array<{
  dimensions: { width: number; height: number; };
  nodes: { [key: string]: number; };
}>;
```

The above would transpose into something along these lines.

```js
[
  { // page 1
    "dimensions": { "width": 1200, "height": 1200 },
    "nodes": {
      "ab:Artboard": 1, "MediaContainer": 1, "Text": 2, "ComplexShape": 3
    }
  },
  { // page 2
    "dimensions": { "width": 800, "height": 400 },
    "nodes": {
      "ab:Artboard": 1, "MediaContainer": 4, "Rectangle": 2
    }
  },
  // ...
]
```

The various `"ab:Artboard"`, `"MediaContainer"` and others, are the Node type strings as Adobe Express exposes them. Let's create the `getDocumentData()` function that outputs such a structure.

![](images/stats-addon-type.png)

<CodeBlock slots="heading, code" repeat="1" languages="code.js"/>

#### documentSandbox/code.js

```js
import { getNodeData } from "./utils";

runtime.exposeApi({
  async getDocumentData() {
    const doc = editor.documentRoot;      // get the document
    let documentData = [];                // initialize the array to return
    for (const page of doc.pages) {       // loop through each page
      let pageData = {};                  // create an empty object
      pageData.dimensions = {             // get and store the page `dimensions`
        width: page.width,
        height: page.height,
      };
      pageData.nodes = getNodeData(page); // 👈 build the `nodes` object (more on this later)
      documentData.push(pageData);        // push the object to the documentData array
    }
    // invoke the iframe method to create the table on the UI
    await panelUIProxy.createTable(documentData);
  },
});
```

The code comments will guide you through the process of getting the document, loop through pages extracting dimensions, and retrieving nodes metadata, but up to a point. What's `getNodeData`? As I mentioned before, I've split the Document API code into two parts: the main Document Sandbox entrypoint (`code.js`, where methods are exposed to and imported from the iframe) and `table-utils.js`, which is kept private to the context and exports just what `code.js` needs—the `getNodeData()` method, which makes use of `increaseCount()`.

<CodeBlock slots="heading, code" repeat="1" languages="utils.js"/>

#### documentSandbox/table-utils.js

```js
const increaseCount = (obj, type) => {
  // If the type is already in the object, increase its count, otherwise set it to 1
  if (obj.hasOwnProperty(type)) {
    obj[type] += 1;
  } else {
    obj[type] = 1;
  }
};

const getNodeData = (node, nodeData = {}) => {
  if (node.type === "MediaContainer") {
    return nodeData;
  }

  // Check if the current node has children and if they are not an empty array
  if (node.allChildren && node.allChildren.length > 0) {
    // Iterate over all children using for..of
    for (const child of node.allChildren) {
      // Increase the count for the current type
      increaseCount(nodeData, child.type);

      // Recursively call getNodeData for each child that has its own children
      // ... unless it's a MediaContainer
      if (
        child.type !== "MediaContainer" &&
        child.allChildren &&
        child.allChildren.length > 0
      ) {
        getNodeData(child, nodeData);
      }
    }
  }

  return nodeData;
};

export { getNodeData };
```

Given the nature of Adobe Express documents (which will be covered in detail in a future tutorial), it makes sense to build `getNodeData()` as a recursive function: a [`PageNode`](/references/document-sandbox/document-apis/classes/PageNode/) can contain multiple [`ArtboardNode`](/references/document-sandbox/document-apis/classes/ArtboardNode/) elements, which in turn can contain multiple [`GroupNode`](/references/document-sandbox/document-apis/classes/GroupNode/) elements, and so on. As follows, the metacode.

1. The `getNodeData()` method begins its execution when called by `getDocumentData()`, taking a single parameter named `page`. At the start, `nodeData` is initialized as an empty object. The method then checks if the current node has the `allChildren` property, which should be a non-empty iterable (please note: it's not an Array, but can be transformed into one if needed via `Array.from()`). If so, it goes through it. During each iteration, it increments the count for the `type` property of each child node (such as `"Text"`, `"Group"`, etc.).

2. If a child node within this array also features a non-empty `allChildren` property, `getNodeData()` is called recursively on that child node. Mind you: during these recursive calls, `nodeData` is passed as the second argument. This approach ensures that the same `nodeData` object is continuously used throughout the recursion, allowing it to accumulate and keep tabs on all node types encountered across all hierarchy levels. The `"MediaContainer"` node is a particular one, [^3] and when encountered, we stop there.  

3. The `increaseCount()` method, which we keep private to the `utils.js` module, receives the `nodeData` object and bumps the count for each `child.type`.

When the whole process is repeated for each `page`, we can finally invoke the iframe `createTable()` method, passing the `documentData`.

<CodeBlock slots="heading, code" repeat="1" languages="code.js"/>

#### documentSandbox/code.js

```js
runtime.exposeApi({
    async getDocumentData() {
      // ... create and fill the `documentData` array
      await panelUIProxy.createTable(documentData); // 👈 calling this iframe proxy method
    },
  });
```

Now, it's up to the iframe to manage such data (the array of objects collecting page dimensions and node counts) and transform it into a Spectrum Table.

<CodeBlock slots="heading, code" repeat="1" languages="index.js"/>

#### ui/index.js

```js
import { rebuildTable } from "./table-utils";

const iframeApi = {
    toggleStatus(sdk) { /* ... */ },
    createTable(documentData) {  // 👈
      const table = document.getElementById("stats-table-body");
      rebuildTable(table, documentData);
    },
  };
```

The process is not difficult per se, but it may be slightly tedious. The `rebuildTable()` method is declared in the `table-utils.js` module alongside a private `addRowToTable()`.

<CodeBlock slots="heading, code" repeat="1" languages="table-utils.js"/>

#### documentSandbox/table-utils.js

```js
// documentSandbox/table-utils.js

const addRowToTable = (table, rowData) => {
  // Create a new row
  const newRow = document.createElement("sp-table-row");

  // For each cell data, create a cell and append it to the row
  let cell;
  rowData.forEach((cellData) => {
    cell = document.createElement("sp-table-cell");
    cell.textContent = cellData;
    newRow.appendChild(cell);
  });
  if (rowData.length === 1) {
    // Making the page row bold
    cell.className = "page-row";
  }
  // Append the row to the table body
  table.appendChild(newRow);
};

const rebuildTable = (table, documentData) => {
  // Removing all existing rows from the table,
  // either the placeholder or the previous results
  while (table.firstChild) {
    table.removeChild(table.firstChild);
  }
  documentData.forEach((pageData, index) => {
    addRowToTable(table, [
      `Page ${index + 1} (${pageData.dimensions.width} x ${
        pageData.dimensions.height
      })`,
    ]);
    // the for...in loop iterates over the keys of an object
    for (const node in pageData.nodes) {
      // for example,      ["Text", 1]
      addRowToTable(table, [node, pageData.nodes[node]]);
    }
  });
};

export { rebuildTable };
```

As follows, the `rebuildTable()` metacode.

- Initialize the existing table, which is the first argument it receives.
- Loop through each page in the `documentData` array, adding a row with the dimensions via  `addRowToTable()`; please note that, although the Table is supposed to have two columns, we can set a row with only one cell, which will span both of them.
- Loop through each node in the `pageData.nodes` object, adding a row with the node type and the number of instances found on that page.
- `addRowToTable()` is a utility function that takes a table and an array of strings as arguments. It creates a new `<sp-table-row>`, then loops through the array, creating a `<sp-table-cell>` for each string and appending it to the row. If the array contains only one element, the cell is given a `page-row` class, which makes it bold.

![](images/stats-addon-stats.png)

## Next Steps

Congratulations! You've coded from scratch the Stats add-on for Adobe Express. As an exercise, you may want to extend it with the following features.

- **Better visualization**: you can add `<sp-icon>` elements for each Node type, or bypass the Table altogether using an Accordion component for a hierarchical, collapsible menu.
- **Hide and Show**: via the [Document API](/references/document-sandbox) you may hide and show elements based on their type—the `<sp-table>` has a `selects` and a `selected` attributes that you can put to use.
- **Save Snapshots**: using the [Client Storage API](/references/addonsdk/instance-clientStorage/), you can keep track of the document's metadata and compare it with previous versions.

## Lessons Learned

Let's review the concepts covered in this tutorial and how they've been implemented in the Stats add-on.

- **Communication API**: the iframe and the Document Sandbox can expose and import each other's API via proxy objects. The Communication API wraps all inter-context function invocations with a Promise; hence, the need to `await` when invoking a proxy method.
- **Proxy API**: the payload objects exchanged between the two contexts can contain functions, which are the most common use case: they can return primitives, object literals, JSON strings, ArrayBuffers, and Blobs.
- **Context Closures**: proxy methods have access to variables defined in their context, even when invoked from the other context. This is a powerful feature that can be exploited to keep private variables and functions out of the Communication API.
- **Roundtrip calls**: proxy methods can be chained—the iframe can invoke the Document API via the Document Sandbox proxy, which in turn can invoke the iframe proxy, and so on.

## Final Project

The code for this project can be downloaded [here](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/express-stats-addon). Use [this template](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/express-addon-document-api-template) as a starting point.

<InlineAlert variant="info" slots="text1" />

Please use the UI iframe and Document Sandbox tabs to switch between the two domains and find a dropdown in the top-right corner to select which file to show.

<!-- Code below -->
<CodeBlock slots="heading, code" repeat="6" languages="index.html, styles.css, ui/index.js, ui/table-utils.js, documentSandbox/code.js, documentSandbox/utils.js" />

#### UI iframe

```html
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <meta name="description"
    content="Adobe Express Add-on template using JavaScript, the Document Sandbox, and Webpack" />
  <meta name="keywords" content="Adobe, Express, Add-On, JavaScript, Document Sandbox, Adobe Express Document API" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Stats add-ons</title>
  <link rel="stylesheet" href="styles.css">
</head>

<body>
  <sp-theme scale="medium" color="light" theme="express">
    <h3>Framework status</h3>
    <hr>
    <div class="row">
      <sp-status-light size="m" variant="negative" id="iframe-status">iFrame API</sp-status-light>
      <sp-status-light size="m" variant="negative" id="document-status">Authoring API</sp-status-light>
    </div>
    <h3>Document statistics</h3>
    <hr>
    <div class="row">
      <sp-table size="m">
        <sp-table-head>
          <sp-table-head-cell>Element</sp-table-head-cell>
          <sp-table-head-cell>Count</sp-table-head-cell>
        </sp-table-head>
        <sp-table-body id="stats-table-body">
          <sp-table-row id="row-placeholder">
            <sp-table-cell>Get the Document stats first...</sp-table-cell>
          </sp-table-row>
        </sp-table-body>
      </sp-table>
    </div>
    <div class="row align-right">
      <sp-button id="stats">Analyze document</sp-button>
    </div>
  </sp-theme>
</body>
</html>
```

#### UI iframe

```css
body {
  margin: 0;
  padding: 0;
  overflow-x: hidden;
}

sp-theme { margin: 0 var(--spectrum-global-dimension-static-size-300); }

.row {
  display: flex;
  flex-direction: row;
  justify-content: space-between;
  margin-bottom: var(--spectrum-global-dimension-static-size-175);
}

.align-right { justify-content: flex-end; }

sp-table { width: 100%; }

sp-button { align-self: flex-end; }

.page-row { font-weight: var(--spectrum-global-font-weight-bold); }
```

#### UI iframe

```js
import "@spectrum-web-components/styles/typography.css";
import "@spectrum-web-components/theme/src/themes.js";
import "@spectrum-web-components/theme/theme-light.js";
import "@spectrum-web-components/theme/express/theme-light.js";
import "@spectrum-web-components/theme/express/scale-medium.js";
import "@spectrum-web-components/theme/sp-theme.js";

import "@spectrum-web-components/status-light/sp-status-light.js";
import "@spectrum-web-components/table/elements.js";
import "@spectrum-web-components/button/sp-button.js";

import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
import { rebuildTable } from "./table-utils";

addOnUISdk.ready.then(async () => {
  const iframeApi = {
    /**
     * Toggles the status light.
     * @param {string} sdk - The type of SDK that is ready, either "document" or "iframe"
     */
    toggleStatus(sdk) {
      if (["document", "iframe"].indexOf(sdk) === -1) {
        throw new Error("Invalid SDK type");
      }
      const el =
        sdk === "document"
          ? document.getElementById("document-status")
          : document.getElementById("iframe-status");
      el.setAttribute("variant", "positive");
    },

    createTable(documentData) {
      const table = document.getElementById("stats-table-body");
      rebuildTable(table, documentData);
    },
  };

  // the addOnUISdk is ready, so we can now toggle the status light
  iframeApi.toggleStatus("iframe");

  // Get the Document Sandbox.
  const { runtime } = addOnUISdk.instance;
  // Importing the Document Sandbox API.
  const sandboxProxy = await runtime.apiProxy("documentSandbox");
  // Exposing the iframe API to the Document Sandbox.
  runtime.exposeApi(iframeApi);

  const statsButton = document.getElementById("stats");

  statsButton.addEventListener("click", async () => {
    await sandboxProxy.getDocumentData();
  });
  // Enabling the button only when the addOnUISdk is ready
  statsButton.disabled = false;
});

/**
 * Adds a new row to the specified table.
 *
 * @param {HTMLTableElement} table - The table to which the row should be added.
 * @param {Array} rowData - An array containing the data for each cell in the row.
 */
function addRowToTable(table, rowData) {
  // Create a new row
  const newRow = document.createElement("sp-table-row");

  // For each cell data, create a cell and append it to the row
  let cell;
  rowData.forEach((cellData) => {
    cell = document.createElement("sp-table-cell");
    cell.textContent = cellData;
    newRow.appendChild(cell);
  });
  if (rowData.length === 1) {
    // Making the page row bold
    cell.className = "page-row";
  }
  // Append the row to the table body
  table.appendChild(newRow);
}

```

#### UI iframe

```js
/**
 * Adds a new row to the specified table.
 *
 * @param {HTMLTableElement} table - The table to which the row should be added.
 * @param {Array} rowData - An array containing the data for each cell in the row.
 */
const addRowToTable = (table, rowData) => {
  // Create a new row
  const newRow = document.createElement("sp-table-row");

  // For each cell data, create a cell and append it to the row
  let cell;
  rowData.forEach((cellData) => {
    cell = document.createElement("sp-table-cell");
    cell.textContent = cellData;
    newRow.appendChild(cell);
  });
  if (rowData.length === 1) {
    // Making the page row bold
    cell.className = "page-row";
  }
  // Append the row to the table body
  table.appendChild(newRow);
};

const rebuildTable = (table, documentData) => {
  // Removing all existing rows from the table
  while (table.firstChild) {
    table.removeChild(table.firstChild);
  }

  // The pageData comes as an array of objects, one for each page
  // Each pageData object contains the dimensions of the page and the nodes, e.g.
  // [{ dimensions: { width: 600, height: 800 }, nodes: { Text: 1, Rectangle: 4 } }, { ... }]
  documentData.forEach((pageData, index) => {
    addRowToTable(table, [
      `Page ${index + 1} (${pageData.dimensions.width} x ${
        pageData.dimensions.height
      })`,
    ]);
    // the for...in loop iterates over the keys of an object
    for (const node in pageData.nodes) {
      // for example,      ["Text", 1]
      addRowToTable(table, [node, pageData.nodes[node]]);
    }
  });
};

export { rebuildTable };
```

#### Document Sandbox

```js
import addOnSandboxSdk from "add-on-sdk-document-sandbox";
const { runtime } = addOnSandboxSdk.instance;

import { editor } from "express-document-sdk";
import { getNodeData } from "./utils";

async function start() {
  const panelUIProxy = await runtime.apiProxy("panel");

  runtime.exposeApi({
    async getDocumentData() {
      const doc = editor.documentRoot;
      let documentData = [];
      for (const page of doc.pages) {
        console.log("Page", page);
        let pageData = {};
        pageData.dimensions = {
          width: page.width,
          height: page.height,
        };
        pageData.nodes = getNodeData(page);
        documentData.push(pageData);
      }
      console.log("documentData", documentData);
      await panelUIProxy.createTable(documentData);
    },
  });

  panelUIProxy.toggleStatus("document");
}

start();
```

#### Document Sandbox

```js
const increaseCount = (obj, type) => {
  // If the type is already in the object, increase its count, otherwise set it to 1
  if (obj.hasOwnProperty(type)) {
    obj[type] += 1;
  } else {
    obj[type] = 1;
  }
};

const getNodeData = (node, nodeData = {}) => {
  if (node.type === "MediaContainer") {
    return nodeData;
  }

  // Check if the current node has children and if they are not an empty array
  if (node.allChildren && node.allChildren.length > 0) {
    // Iterate over all children using for..of
    for (const child of node.allChildren) {
      // Increase the count for the current type
      increaseCount(nodeData, child.type);

      // Recursively call getNodeData for each child that has its own children
      // ... unless it's a MediaContainer
      if (
        child.type !== "MediaContainer" &&
        child.allChildren &&
        child.allChildren.length > 0
      ) {
        getNodeData(child, nodeData);
      }
    }
  }
  return nodeData;
};

export { getNodeData };
```

[^0]: When referring to "metadata", I mean the dimensions and types of elements on each page. Custom metadata haven't been implemented in Adobe Express yet.

[^1]: In my tests, the two SDKs are ready almost instantly and together—I couldn't tell which one is loaded firsts.

[^2]: Designing data structures in the early stages of the development process is, in my humble opinion, a way to dodge a good deal of future headaches.

[^3]:  A `"MediaContainer"` (say, an image) has as children both the `"ImageRectangle"` and the mask that crops it. At this stage of the Document API development, getting complex masks may throw an Error—hence, I've decided to use the `"MediaContainer"` type as a recursion's termination clause.
# addOnUISdk.app

Provides access to the Adobe Express host application's objects and methods to provide features such as content import and export through the [`document` object](./app-document.md), OAuth 2.0 authorization flows with the [`oauth` object](./app-oauth.md), theme and locale detection with the [`ui` object](app-ui.md), [current logged in user info](./app-currentUser.md) and more. It also provides access to methods to [show modal dialogs](../../guides/develop/how_to/modal_dialogs.md), [enable drag and drop](../../guides/develop/how_to/drag_and_drop.md) of content and subscribe and unsubscribe to events.

## Objects

<table class="spectrum-Table spectrum-Table--sizeM" css="
    background-color:lavender;
    tbody {
      background-color:white;
    }">
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-headCell"><p><strong>Attribute</strong></p></td>
    <td class="spectrum-Table-headCell"><p><strong>Name</strong></p></td>
    <td class="spectrum-Table-headCell"><p><strong>Type</strong></p></td>
    <td class="spectrum-Table-headCell"><p><strong>Description</strong></p></td>
</tr>
<tbody class="spectrum-Table-body">
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>readonly</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre><a href="app-currentUser.md">currentUser</a></pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>object</pre></p></td>
    <td class="spectrum-Table-cell"><p>Represents the current user accessing the host application</p></td>
  </tr>
  <tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre></pre></p></td>
    <td class="spectrum-Table-cell"><p><pre><a href="app-devFlags.md">devFlags</a></pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>object</pre></p></td>
    <td class="spectrum-Table-cell"><p>Represents flags which can be used to simulate certain behavior during development.</p></td>
  </tr>
  <tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>readonly</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre><a href="app-document.md">document</a></pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>object</pre></p></td>
    <td class="spectrum-Table-cell"><p>Represents the active document of the host application.</p></td>
  </tr>
  <tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>readonly</pre></p></td>
     <td class="spectrum-Table-cell"><p><pre><a href="app-oauth.md">oauth</a></pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>object</pre></p></td>
    <td class="spectrum-Table-cell"><p>Provides access to the OAuth methods needed to implement OAuth 2.0 for user authorization.</p></td>
  </tr>
  <tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>readonly</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre><a href="app-ui.md">ui</a></pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>object</pre></p></td>
    <td class="spectrum-Table-cell"><p>Represents the host UI (Adobe Express UI).</p></td>
  </tr>  
  
</tbody>
</table>

## Methods

### on()

Subscribe to an event (ie: listen for an event).

#### Signature

`on(name: string, handler: eventHandler): void`

#### Parameters

| Name      | Type                | Description                                            | Valid Values          |
| --------- | ------------------- | ------------------------------------------------------ | --------------------- |
| `name`    | `string`            | Event to subscribe to.                                 | See [Events](#events) |
| `handler` | callback `function` | Handler that gets invoked when the event is triggered. | `(data) => {}`        |

#### Return Value

`void`

#### Example Usage

```js
addOnUISdk.app.on("themechange", (data) => {
  applyTheme(data.theme);
});
```

### off()

Unsubscribe from an event (ie: stop listening for an event).

#### Signature

`off(name: string, handler: eventHandler): void`

#### Parameters

| Name      | Type                | Description                                      | Valid Values          |
| --------- | ------------------- | ------------------------------------------------ | --------------------- |
| `name`    | `string`            | Event to unsubscribe to.                         | See [Events](#events) |
| `handler` | callback `function` | Handler that was used during event subscription. | `(data) => {}`        |

#### Return Value

`void`

#### Example Usage

```js
addOnUISdk.app.off("themechange", (data) => {
  applyTheme(data.theme);
});
```

### startPremiumUpgradeIfFreeUser()

Displays the in-app monetization upgrade flow.

#### Signature

`startPremiumUpgradeIfFreeUser(): Promise<boolean>`

#### Return Value

Returns a resolved `Promise` with a value of `true` if the user is premium or completed the flow, and `false` if the user is a free user and cancelled the upgrade.

#### Example Usage

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  const isPremiumUser = await addOnUISdk.app.startPremiumUpgradeIfFreeUser();
  if (!isPremiumUser) {
    // User did not upgrade, show error dialog
  }
});
```

### showModalDialog()

Shows a modal dialog based on specific options passed in.

#### Signature

`showModalDialog(dialogOptions: DialogOptions): Promise<DialogResult>`

#### Parameters

| Name            | Type     |                                      Description |
| --------------- | -------- | -----------------------------------------------: |
| `dialogOptions` | `object` | [`DialogOptions`](#dialogoptions) object payload |

##### `DialogOptions`

| Name            |                                        Type |                                      Description |
| --------------- | ------------------------------------------: | -----------------------------------------------: |
| `variant`       | `string` [Variant](./addonsdk-constants.md) |                      The type of dialog to show. |
| `title`         |                                    `string` |                                     Dialog title |
| `description`   |                                    `string` |                      Description for the dialog. |
| `buttonLabels?` |      `object` [ButtonLabels](#buttonlabels) | The optional button labels to use in the dialog. |

##### `ButtonLabels`

| Name         |     Type |                                  Description |
| ------------ | -------: | -------------------------------------------: |
| `primary?`   | `string` | Primary action label. Default label is "OK". |
| `secondary?` | `string` |                      Secondary action label. |
| `cancel?`    | `string` |                         Cancel action label. |

The input dialog variant accepts an [additional `field`](#input-dialog-additional-option) object.

##### Input Dialog Additional Option

| Name    |                     Type |        Description |
| ------- | -----------------------: | -----------------: |
| `field` | object [`Field`](#field) | Input field object |

##### `Field`

| Name          |     Type |                                                           Description |
| ------------- | -------: | --------------------------------------------------------------------: |
| `label`       | `string` |                                             Label for the input field |
| `placeholder` | `string` | Specifies a short hint that describes the expected value of the field |
| `fieldType`   | `string` |                                    Currently always the value "text". |

#### Return Value

Returns a `Promise` [`DialogResult`](#dialogresult) object with the [button type](../addonsdk/addonsdk-constants.md) that was clicked, or an error. When using the "input" dialog variant, an additional `fieldValue` property will be in the response object and will contain the value of the field the user input text to.

#### `DialogResult`

| Name         | Type                                                                |              Description |
| ------------ | ------------------------------------------------------------------- | -----------------------: |
| `buttonType` | `string` [`ButtonType`](../addonsdk/addonsdk-constants.md) constant |  The button type clicked |
| `fieldValue` | `string`                                                            | The input from the user. |

#### Confirmation Dialog Example Usage

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;

async function showConfirmDialog() {
  try {
    // Confirmation Dialog Example
    let dialogOptions = {
      variant: "confirmation",
      title: "Enable smart Filters",
      description:
        "Smart filters are nondestructive and will preserve your original images.",
      buttonLabels: { primary: "Enable", cancel: "Cancel" },
    };
    const result = await addOnUISdk.app.showModalDialog(dialogOptions);
    console.log("Button type clicked " + result.buttonType);
  } catch (error) {
    console.log("Error showing modal dialog:", error);
  }
}
```

#### Input Dialog Example Usage

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;

async function showInputDialog() {
  try {
    // Input Dialog Example
    let inputDialogOptions = {
      variant: "input",
      title: "Please enter your key",
      description: "Your API key",
      buttonLabels: { cancel: "Cancel" },
      field: {
        label: "API Key",
        placeholder: "Enter API key",
        fieldType: "text",
      },
    };

    const inputDialogResult = await addOnUISdk.app.showModalDialog(
      inputDialogOptions
    );
    if (inputDialogResult.buttonType === "primary") {
      console.log("Field value " + inputDialogResult.fieldValue); // returns the input the user entered if they didn't cancel
    }
  } catch (error) {
    console.log("Error showing modal dialog:", error);
  }
}
```

<InlineAlert slots="text" variant="info"/>

See the use case implementations for an example of the [custom modal dialog](../../guides/develop/how_to/modal_dialogs.md#custom-dialog).

### showColorPicker()

Shows the Adobe Express color picker based on specific options passed in.

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently **_experimental only_** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../manifest/index.md#requirements) section of the `manifest.json`.

#### Signature

`showColorPicker(anchorElement: HTMLElement, options?: ColorPickerOptions): Promise<void>;`

#### Parameters

| Name            | Type                 |                                       Description |
| --------------- | -------------------- | ------------------------------------------------: |
| `anchorElement` | `HTMLElement`        |        The element to anchor the color picker to. |
| `options`       | `ColorPickerOptions` | The optional options to pass to the color picker. |

##### `ColorPickerOptions`

| Name                     |                                                               Type |                                                                                                                                                                                                                                                                      Description |
| ------------------------ | -----------------------------------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `title?`                 |                                                           `string` |                                                                                                                                                                                                                     Label header/title for the color picker. Default value: `""` |
| `initialColor?`          |                                                           `number` | Default/starting color when you open the color picker for the first time on a `anchorElement`. When you have already changed the color with this picker, then the next time you open the picker, the last selected color will be the starting color. Default: `0xFFFFFF` (white) |
| `placement?`             | `object` [ColorPickerPlacement](./addonsdk-constants.md#constants) |                                                                                                                                                                                                 Placement of the popover with respect to the anchor element (default: `"left"`). |
| `eyedropperHidesPicker?` |                                                          `boolean` |                                                                                                                Closes the color picker popover while using the EyeDropper. After the color is selected via the EyeDropper, the color picker popup opens again. Default: `false`. |
| `disableAlphaChannel?`   |                                                          `boolean` |                                                                                                                                                                                  Disables the transparency slider in the "custom" section of the color picker. Default: `false`. |

#### Return Value

Returns a void `Promise`.

#### Example Usage

```js
const colorPickerButton = document.getElementById("color-picker-button");

colorPickerButton.addEventListener("click", () => {
  addOnUISdk.app.showColorPicker(colorPickerButton, {
    title: "Add-on's Color Picker",
    placement: ColorPickerPlacement.left,
    eyedropperHidesPicker: true,
    disableAlphaChannel: false,
  });
});

colorPickerButton.addEventListener(ColorPickerEvents.colorChange, (event) => {
  console.log("Color change event received!", event.detail.color;);
});
```

### hideColorPicker()

Hides the Adobe Express color picker.

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently **_experimental only_** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../manifest/index.md#requirements) section of the `manifest.json`.

#### Signature

`hideColorPicker(): Promise<void>;`

#### Return Value

Returns a void `Promise`.

#### Example Usage

```js
const colorPickerButton = document.getElementById("color-picker-button");

colorPickerButton.addEventListener("click", () => {
  addOnUISdk.app.showColorPicker(colorPickerButton, {
    title: "Add-on's Color Picker",
    placement: ColorPickerPlacement.left,
    eyedropperHidesPicker: true,
    disableAlphaChannel: false,
  });
  setTimeout(() => {
    console.log("Hiding Color Picker after 10 seconds...");
    addOnUISdk.app.hideColorPicker();
  }, 10000);
});
```

### registerIframe()

Allows an iframe hosted within an add-on to register its intent to communicate with the add-on SDK. While iframes can be used for embedding media without SDK interaction, `registerIframe()` is needed for those requiring SDK capabilities. It marks a transition to a more controlled approach, where add-ons must explicitly opt-in to this level of integration.

#### Signature

`registerIframe(element: HTMLIFrameElement): [UnregisterIframe]()`

#### Parameters

| Name      | Type                |             Description |
| --------- | ------------------- | ----------------------: |
| `element` | `HTMLIFrameElement` | The iframe to register. |

#### Return Value

[`UnregisterIframe`](#unregisteriframe-type-definition)

##### `UnregisterIframe` Type Definition

Callback function that unregisters the previously registered iframe, ceasing its direct communication with the add-on SDK. Returns `void`.

```ts
type UnregisterIframe = () => void;
```

#### Example Usage

```ts
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

function RegisterIframe(elementId: string) {
  const iframe = document.getElementById(elementId);
  try {
    unregisterIframe = addOnUISdk.app.registerIframe(iframe);
  } catch (error) {
    console.log("Failed to register iframe with the SDK:", error);
  }
}

addOnUISdk.ready.then(() => {
  let unregisterIframe: UnregisterIframe = RegisterIframe("iframe1");
  // ...
  unregisterIframe();
  unregisterIframe = RegisterIframe("iframe2");
  // ...
  unregisterIframe();
});
```

### enableDragToDocument()

Allows for drag and document functionality to be enabled on an element such as an image, video or audio.

<InlineAlert slots="text" variant="info"/>

**IMPORTANT:** If the content being dragged is an animated GIF, it will be added as an animated GIF to the document, as long as it fits [the size criteria for animated GIF's](https://helpx.adobe.com/express/create-and-edit-videos/change-file-formats/import-gif-limits.html). In the event that it doesn't fit the size criteria, an error toast will be shown to the user.

#### Signature

`enableDragToDocument(element: HTMLElement, dragCallbacks: DragCallbacks): [DisableDragToDocument]()`

#### Parameters

| Name            | Type                            |                                            Description |
| --------------- | ------------------------------- | -----------------------------------------------------: |
| `element`       | `HTMLElement`                   |               The element to enable for drag and drop. |
| `dragCallbacks` | [dragCallbacks](#dragcallbacks) | An object containing a preview and completion callback |

##### `dragCallbacks`

| Name                 | Type                                                                |                                                 Description |
| -------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------: |
| `previewCallback`    | [`DragPreviewCallback`](#dragpreviewcallback-type-definition)       |                       Callback to provide the preview image |
| `completionCallback` | [`DragCompletionCallback`](#dragcompletioncallback-type-definition) | Callback to provide the content to be added to the document |

##### `DragPreviewCallback` Type Definition

Callback used to get the preview image for the drag & drop action. Returns a `URL` object.

```ts
type DragPreviewCallback = (element: HTMLElement) => URL;
```

##### `DragCompletionCallback` Type Definition

Callback to provide the content (image/gif/video/audio) to be added to the document post drag & drop action. Returns [DragCompletionData](#dragcompletiondata) array.

```ts
type DragCompletionCallback = (
  element: HTMLElement
) => Promise<DragCompletionData[]>;
```

##### `DragCompletionData`

Returned as part of an array from the [`DragCompletionCallback`](#dragcallbacks), and contains the `blob` object to be added, as well as a [`MediaAttributes`](#mediaattributes) object with the `title` of the audio content (for audio only).

| Name          | Type                                  |                                                                             Description |
| ------------- | ------------------------------------- | --------------------------------------------------------------------------------------: |
| `blob`        | `Blob`                                |                                    Blob (image/video/audio) to be added to the document |
| `attributes?` | [`MediaAttributes`](#mediaattributes) | Attributes to pass when adding the audio to the page (ie: `title`, which is mandatory). |

#### `MediaAttributes`

_Required for audio content only._

| Name    | Type     |                               Description |
| ------- | -------- | ----------------------------------------: |
| `title` | `string` | Media title (mandatory for audio import). |

#### Return Value

[`DisableDragToDocument`](#disabledragtodocument-type-definition)

##### `DisableDragToDocument` Type Definition

Callback to undo the changes made by `enableDragToDocument`. Returns `void`.

```ts
type DisableDragToDocument = () => void;
```

##### `DragStartEventData` Object

The payload data sent to the `dragStart` event handler.

###### Properties

| Name      | Type          |                              Description |
| --------- | ------------- | ---------------------------------------: |
| `element` | `HTMLElement` | Element for which the drag event started |

##### `DragEndEventData`

The payload data sent to the App `dragEnd` event handler.

| Name                | Type          |                                     Description |
| ------------------- | ------------- | ----------------------------------------------: |
| `element`           | `HTMLElement` |          Element for which the drag event ended |
| `dropCancelled`     | `boolean`     | If drop occurred/drag ended at invalid position |
| `dropCancelReason?` | `string`      |                    Reason for drop cancellation |

**\* Important Event Handling Notes**<br/>

- Since the `addOnUISdk` uses pointer event handlers to perform drag operations, you should ensure that you don't attach any pointer event handlers that prevent default or stop propagation. Adding those types of handlers will kill the built-in handlers and cause the events not to work.
- You should not attach `click` event listeners to drag-enabled elements in the capture phase, as the `addOnUISdk` attaches a `cancelClickEvent` handler to drag-enabled elements to ensure that the automatic click (pointer down + pointer up automatically fires a click event) doesn't fire. Adding other handlers to this same element will cause them to be triggered on drag & drop completion.
- TIP: Use Chrome devTools to check the handlers attached to the element and its ancestors to identify any which may be causing conflicts with drag and drop handlers.

<InlineAlert slots="text" variant="info"/>

See the [Drag & Drop use case implementation](../../guides/develop/how_to/drag_and_drop.md) for example usage, and the [code samples](/samples.md) provided for reference.

## Events

The table below describes the events triggered from the add-on SDK. Use the `addOnUISdk.app.on()` method to subscribe to events, and the `addOnUISdk.app.off()` method to unsubscribe from them. See the [`on()`](#on) method reference for more details.

<table class="spectrum-Table spectrum-Table--sizeM" css="
    background-color:lavender;
    tbody {
      background-color:white;
    }">
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-headCell"><p><strong>Type</strong></p></td>
    <td class="spectrum-Table-headCell"><p><strong>Description</strong></p></td>
</tr>
<tbody class="spectrum-Table-body">
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>localechange</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Triggered when there is a locale change at the host side.</p>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>themechange</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Triggered when there is a theme change at the host side.</p>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>dragstart</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Triggered when the user starts dragging an item for which drag behavior is enabled.</p>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>dragend</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Triggered when the drag operation ends.</p>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>documentIdAvailable</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Triggered when the document id is available in the application.</p>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>documentTitleChange</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Triggered when the document title is changed in the application.</p>
    </td>
</tr>
</tbody>
</table>

## Errors

The table below describes the possible error messages that may occur when using the core `addOnUISdk.app` methods, with a description of the scenario that will return them.

<br/>

|                                                                              Error Message |                                                                Error Scenario |
| -----------------------------------------------------------------------------------------: | ----------------------------------------------------------------------------: |
|                                         Incorrect type: element must of type `HTMLElement` | Element passed to `enableDragToDocument` is not an instance of `HTMLElement`. |
|               Incorrect return type: `PreviewCallback` must return an object of type `URL` |                                `previewCallback` function doesn't return URL. |
| Incorrect return type: `CompletionCallback` should return an array of `DragCompletionData` |                   `completionCallback` doesn't return `DragCompletionData[]`. |
|                                 Dialog already open with instanceID: `${this._instanceId}` |                                                       Dialog is already open. |
|                                               Dialog options parameter: title is undefined |                                                           Title is undefined. |
|                                         Dialog options parameter: description is undefined |                                                     Description is undefined. |
|                                             Dialog options parameter: variant is undefined |                                                         Variant is undefined. |
|                                                       Invalid dialog variant: `${variant}` |                                                       Invalid dialog variant. |
|                                                            Input dialog field is undefined |                           Text field property is undefined for input variant. |
|                                              Field property is valid only for input dialog |               If text field property is present for variant other than input. |
|                                                      Input dialog field label is undefined |                            Field label is undefined for input dialog variant. |
|                                            Invalid dialog field type: `${field.fieldType}` |                               Field type is invalid for input dialog variant. |
|                                  Dialog already open with instanceID:`${this._instanceId}` |                                                If the dialog is already open. |
|                                               Dialog options parameter: title is undefined |                                                           Title is undefined. |
|                                                 Dialog options parameter: src is undefined |                                                          Source is undefined. |
|                                                       Invalid dialog variant: `${variant}` |                                                       Invalid dialog variant. |
# addOnUISdk.constants

A set of constants used throughout the add-on SDK. These constants are equal to their variable name as a string value, ie: for the `ButtonType` constant, `primary` has a value of "primary".

## Constants

<table columnWidths="30,20,60" class="spectrum-Table spectrum-Table--sizeM" css="
    background-color:lavender;
    tbody {
      background-color:white;
    }">
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-headCell"><p><strong>Name</strong></p></td>
    <td class="spectrum-Table-headCell"><p><strong>Type</strong></p></td>
    <td class="spectrum-Table-headCell"><p><strong>Description</strong></p></td>
</tr>
<tbody class="spectrum-Table-body">
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>BleedUnit</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Units for the page bleed.</p>
        <ul>
          <li><strong>"in" (`Inch`)</strong></li>Inch units.
          <li><strong>"mm" (`Millimeter`)</strong></li>Millimeter units.
        </ul>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>ButtonType</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>The type of the button pressed in a dialog.</p>
        <ul>
          <li><strong>primary</strong></li>Primary button pressed.
          <li><strong>secondary</strong></li>Secondary button pressed.
          <li><strong>cancel</strong></li>Cancel button pressed.
          <li><strong>close</strong></li>Dialog closed via ESC or close(X) button.
        </ul>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>ColorPickerEvents</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Custom events dispatched by the Color Picker.</p>
        <ul>
          <li><strong>colorChange</strong></li><pre>"colorpicker-color-change"</pre>
          <li><strong>close</strong></li><pre>"colorpicker-close"</pre>
        </ul>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>ColorPickerPlacement</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Placement of the color picker popover with respect to the anchor element.</p>
        <ul>
          <li><strong>top</strong></li><pre>"top"</pre>
        <li><strong>bottom</strong></li><pre>"bottom"</pre>
        <li><strong>left</strong></li><pre>"left"</pre>
        <li><strong>right</strong></li><pre>"right"</pre>
        </ul>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>DialogResultType</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>The type of modal dialog result.</p>
        <ul>
          <li><strong>alert</strong></li>Alert dialog result (simple dialogs all return this).
          <li><strong>input</strong></li>Input dialog result.
          <li><strong>custom</strong></li>Custom dialog result.
        </ul>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>EditorPanel</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>The Adobe Express Editor panel to be opened.</p>
        <ul>
          <li><strong>search</strong></li>Editor Search panel.
          <li><strong>yourStuff</strong></li>Editor Your stuff panel.
          <li><strong>templates</strong></li>Editor Templates panel.
          <li><strong>media</strong></li>Editor Media panel.
          <li><strong>text</strong></li>Editor Text panel.
          <li><strong>elements</strong></li>Editor Elements panel.
          <li><strong>grids</strong></li>Editor Grids panel.
          <li><strong>brands</strong></li>Editor Brands panel.
          <li><strong>addOns</strong></li>Editor Add-ons panel.
        </ul>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>ElementsTabs</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Tabs in the Editor's Elements panel.</p>
        <ul>
          <li><strong>designAssets</strong></li>Design assets tab.
          <li><strong>backgrounds</strong></li>Backgrounds tab.
          <li><strong>shapes</strong></li>Shapes tab.
          <li><strong>stockIcons</strong></li>Icons tab.
          <li><strong>charts</strong></li>Charts tab.
        </ul>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>LinkOptions</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>The type of link</p>
        <ul>
          <li><strong>document</strong></li>Link to the current document.
        </ul>
    </td>
</tr>

<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>MediaTabs</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Tabs in the Editor's Media panel.</p>
        <ul>
          <li><strong>video</strong></li>Video tab.
          <li><strong>audio</strong></li>Audio tab.
          <li><strong>photos</strong></li>Photos tab.
        </ul>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>PanelActionType</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Types of actions that can be performed on Editor panels.</p>
        <ul>
          <li><strong>search</strong></li>Action type to perform search within the Editor panel.
          <li><strong>navigate</strong></li>Action type to perform navigation within the Editor panel.
        </ul>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>Range</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Rendition page range. Options:</p>
        <ul>
          <li><strong>currentPage</strong></li> Generate rendition for the current page
          <li><strong>entireDocument</strong></li>Generate rendition for all pages
          <li><strong>specificPages</strong></li>Generate rendition for specific pages
        </ul>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>RenditionFormat</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Required output format of the rendition.</p>
        <ul>
          <li><strong>jpg</strong></li>"image/jpeg" for JPG format
          <li><strong>png</strong></li>"image/png" for PNG format
          <li><strong>mp4</strong></li>"video/mp4" for MP4 format
          <li><strong>pdf</strong></li>"application/pdf" for PDF format
        </ul>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>RenditionIntent</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">  
        <p>The intent to set for creating the rendition. Options:</p>
        <ul>
          <li><strong>preview</strong></li>Intent to preview the content.
          <li><strong>export</strong></li>Intent to export/download the content (default).
          <li><strong>print</strong></li>Intent to export and print the content **Note:** For `pdf` format, a print optimized pdf is generated. This option is not supported for `mp4` format.
        </ul>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>RenditionType</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>The type of rendition. Currently returns "page".</p>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>RuntimeType</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Runtime type of the entrypoint creating this backend object.
        <ul>
          <li><strong>panel</strong></li>add-on's iframe runtime, ie: code running in <b>index.html</b>
          <li><strong>script</strong></li>add-on's document sandbox code ie: code running in <b>code.js</b>
          <li><strong>dialog</strong></li>currently open dialog code
        </ul>
        </p>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>Variant</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Types of dialog variants supported.</p>
        <ul>
          <li><strong>confirmation</strong></li>Ask a user to confirm an action.
          <li><strong>information</strong></li>Share information for user to acknowledge.
          <li><strong>warning</strong></li>Share information that a user needs to consider before proceeding.
          <li><strong>destructive</strong></li>Tell a user that if they proceed with an action, it may impact their data in a negative way.
          <li><strong>error</strong></li>Communicate critical issue that a user needs to resolve before proceeding.
          <li><strong>input</strong></li>Ask a user to provide some inputs.
          <li><strong>custom</strong></li>A dialog that can render complex forms and content.
        </ul>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>VideoResolution</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td style="vertical-align: bottom;">
        <p>Video resolution options for the mp4 renditions.</p>
        <ul>
          <li><strong>sd480p</strong></li>"480p"
          <li><strong>hd720p</strong></li>"720p"
          <li><strong>fhd1080p</strong></li>"1080p"
          <li><strong>custom</strong></li>Custom resolution
        </ul>
    </td>
</tr>
</tbody>
</table>
# addOnUISdk.instance

Represents the currently running add-on instance. This object is used to provide access to the `clientStorage` and `manifest` objects. See the [Storing and Retrieving Client Side Data](../../guides/develop/how_to/local_data_management.md) use case implementation and [Manifest](../manifest) reference for more details.

## Objects

<table columnWidths="20,50,30" class="spectrum-Table spectrum-Table--sizeM" css="
    background-color:lavender;
    tbody {
      background-color:white;
    }">
<tr class="spectrum-Table-row">
    <td><p><strong>Attribute</strong></p></td>
    <td><p><strong>Object</strong></p></td>
    <td><p><strong>Description</strong></p></td>
</tr>
<tbody>
<tr class="spectrum-Table-row">
    <td><p><pre>readonly</pre></p></td>
    <td width="80%" style="font-size: 8px"><p><pre>addOnUiSdk.instance.clientStorage</pre></p></td>
    <td>
        <p>Reference to the client storage object of the add-on.</p>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td><p><pre>readonly</pre></p></td>
    <td ><p><pre>addOnUISdk.instance.manifest</pre></p></td>
    <td>
        <p>Add-ons manifest details. Maps to entries in the add-ons manifest file.</p>
    </td>
</tr>
<tr class="spectrum-Table-row">
    <td><p><pre>readonly</pre></p></td>
    <td><p><pre>addOnUISdk.instance.runtime</pre></p></td>
    <td>
        <p>Represents the current add-on runtime.</p>
    </td>
</tr>
</tbody>
</table>
# addOnUISdk

The core add-on UI SDK object which provides access to everything needed for add-on development. This includes determining the current version of the platform, an object to use for determining when the SDK has been initialized and ready for use, and other core objects you can use to access specific features you may want to use for building your add-on.

## addOnUISdk Properties

<table class="spectrum-Table spectrum-Table--sizeM" css="
    background-color:lavender;
    tbody {
      background-color:white;
    }">
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-headCell"><p><strong>Attribute</strong></p></td>
    <td class="spectrum-Table-headCell"><p><strong>Name</strong></p></td>
    <td class="spectrum-Table-headCell"><p><strong>Type</strong></p></td>
    <td class="spectrum-Table-headCell"><p><strong>Description</strong></p></td>
</tr>
<tbody class="spectrum-Table-body">
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>readonly</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>addOnUISdk.apiVersion</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td class="spectrum-Table-cell"><p>Current version of the add-on SDK running.</p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>readonly</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>addOnUISdk.app</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>object</pre></p></td>
    <td class="spectrum-Table-cell"><p>Provides access to the host application (Adobe Express)</p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre></pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>addOnUISdk.constants</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>object</pre></p></td>
    <td class="spectrum-Table-cell"><p>A set of constants used throughout the add-on SDK.</p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>readonly</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>addOnUISdk.instance</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>object</pre></p></td>
    <td class="spectrum-Table-cell"><p>The currently running add-on instance.</p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>readonly</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>AddOnSdk.ready</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>Promise</pre></p></td>
    <td class="spectrum-Table-cell"><p>Indicates the addOnUISdk object has been initialized and you can start accessing the APIs. Register a call back with [Promise.then](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then) or [await this promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await).</p></td>
</tr>
</tbody>
</table>

<!-- ## Methods

## ready
Asynchronous

## Example Usage:
await AddOnSdk.ready; --># addOnUISdk.app.currentUser

Provides access to the currently logged in user.

## Methods

### userId()

Retrieve the current user of the host application (Adobe Express).

#### Signature

`userId(): Promise<string>`

#### Return Value

A resolved `Promise` containing the `userId` of the current user.

## Example

<CodeBlock slots="heading, code" repeat="2" languages="JavaScript" />

### Usage

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
    const userId = await addOnUISdk.app.currentUser.userId();
    console.log("Current Userid: " + userId);
});
```

### Output

`Current Userid: 3cda976828a4a90d13b0f38b1f8a59b1d6845cccfc48037fb30bb75d3ef67d36`

### isPremiumUser()

Indicates if the current user is a premium user.

#### Signature

`isPremiumUser(): Promise<boolean>`

#### Return Value

A resolved `Promise` containing a boolean value indicating if the user is a premium user or not.

## Example

### Usage

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
 
addOnUISdk.ready.then(async () => {
  const isPremiumUser = await addOnUISdk.app.currentUser.isPremiumUser();
  if (!isPremiumUser) {
    // User not premium, allow only non-premium features only
  }
});
```
# addOnUISdk.app.devFlags

This object contains flags which can be used to simulate certain behavior during development.

<InlineAlert slots="text" variant="warning"/>

`addOnUISdk.app.devFlags` are provided for testing purposes only, and thus can only be used during the development phase.

## Methods

### simulateFreeUser

Simulate APIs as a free user.

#### Signature

`simulateFreeUser: boolean`

#### Return Value

`boolean` representing the current value of the flag.

## Example

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  addOnUISdk.app.devFlags.simulateFreeUser = true;
});
```

See this [export content use case example](../../guides/develop/how_to/premium_content.md#show-a-premium-content-error-with-the-upgrade-option), which uses this flag for more details.
# addOnUISdk.app.document

Provides access to the methods needed for retrieving [document metadata](#general-methods), [importing content](../../guides/develop/how_to/use_images.md#import-images-into-the-page) such as images, audio and video into the document, and for [exporting content](../../guides/develop/how_to/create_renditions.md) from the current document.

## General Methods

### id()

Retrieves the id of the document.

#### Signature

`id(): Promise<string | undefined>`

#### Return Value

A resolved `Promise` containing the `id` of the document.

<InlineAlert slots="text" variant="info"/>

**Note:** A `documentIdAvailable` event is triggered when the document id is available in the application. You can listen for this event via the [`addOnUISdk.app.on()`](./addonsdk-app.md#on) method.

#### Example

<CodeBlock slots="heading, code" repeat="1" languages="JavaScript" />

#### Usage

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

function setId(id) { /* ... */ }

addOnUISdk.ready.then(() => setId(await addOnUISdk.app.document.id()));

addOnUISdk.app.on("documentIdAvailable", data => {
  setId(data.documentId);
});
```

### title()

Retrieves the title/name of the document.

#### Signature

`title(): Promise<string>`

#### Return Value

A resolved `Promise` containing the `title` (ie: name) of the document.

<InlineAlert slots="text" variant="info"/>

**Note:** A `documentTitleChange` event is triggered when the document title is changed in the application. You can listen for this event via the [`addOnUISdk.app.on()`](./addonsdk-app.md#on) method.

#### Example

<CodeBlock slots="heading, code" repeat="1" languages="JavaScript" />

#### Usage

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

function setTitle(title) { /* ... */ }

addOnUISdk.ready.then(() => setTitle(await addOnUISdk.app.document.title()));

addOnUISdk.app.on("documentTitleChange", data => {
  setTitle(data.documentTitle);
});
```

### getPagesMetadata()

Retrieve the metadata for all of the pages in the document.

#### Signature

`getPagesMetadata(options: PageMetadataOptions): Promise<PageMetadata[]>`

#### Parameters

| Name      | Type     |                                           Description |
| --------- | -------- | ----------------------------------------------------: |
| `options` | `Object` | [`PageMetadataOptions`](#pagemetadataoptions) object. |

#### Return Value

A resolved `Promise` containing a [`PageMetadata`](#pagemetadata) array containing all of the pages in the document.

<CodeBlock slots="heading, code" repeat="2" languages="JavaScript, bash" />

## Usage

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;

// Get metadata of all the pages
async function logMetadata() {
  try {
    const pages = (await addOnUISdk.app.document.getPagesMetadata({
                            range: addOnUISdk.constants.Range.specificPages,
                            pageIds: [
                                "7477a5e7-02b2-4b8d-9bf9-f09ef6f8b9fc",
                                "d45ba3fc-a3df-4a87-80a5-655e5f8f0f96"
                            ]
                        })) as PageMetadata[];
    for (const page of pages) {
      console.log("Page id: ", page.id);
      console.log("Page title: ", page.title);
      console.log("Page size: ", page.size);
      console.log("Page has premium content: ", page.hasPremiumContent);
      console.log("Page has timelines: ", page.hasTemporalContent);
      console.log("Pixels per inch: ", page.pixelsPerInch);
      console.log("Is page print ready: ", page.isPrintReady);
      console.log("Is page blank: ", page.isBlank);
      console.log("Template details: ", page.templateDetails);
    }
  }
  catch(error) {
    console.log("Failed to get metadata:", error);
  }
}
```

## Output

```bash
Page id: 772dc4b6-0df5-469f-b477-2a0c5445a6ef
Page title: My First Page
Page size: { width: 2550, height: 3300 }
Page has premium content: false
Page has timelines: false
Pixels per inch: 72
Is page print ready: true
Is page blank: false
Template details of page: { id: 'urn:aaid:sc:VA6C2:0ccab100-a230-5b45-89f6-7e78fdf04141', creativeIntent: 'flyer' }
```

### runPrintQualityCheck()

Tells Express to run a print quality check to determine if the document is ready for printing and updates the quality metadata with the result. For instance, if the document is not ready for printing, the `isPrintReady` property of the page metadata will be set to `false`.

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This method is currently **_experimental only_** and should not be used in any add-ons you will be distributing until it has been declared stable. To use this method, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../references/manifest/index.md#requirements) section of the `manifest.json`.

#### Signature

`runPrintQualityCheck(options: PrintQualityCheckOptions): void`

#### Parameters

| Name      | Type     |                                                     Description |
| --------- | -------- | --------------------------------------------------------------: |
| `options` | `Object` | [`PrintQualityCheckOptions`](#printqualitycheckoptions) object. |

#### Return Value

`void`

<CodeBlock slots="heading, code" repeat="2" languages="JavaScript" />

#### Usage

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Reference to the active document
const { document } = addOnUISdk.app;

// Run Print Quality Check
function runPrintQualityCheck() {
  try {
    document.runPrintQualityCheck({
      range: addOnUISdk.constants.Range.entireDocument,
    });
    console.log("Print quality check completed successfully");
  } catch (error) {
    console.log("Failed to run print quality check");
  }
}
```

#### Output

```bash
Print quality check completed successfully
```

#### `TemplateDetails`

Retrieve the details about the template used to create the document.

| Name              | Type     | Description                     |
| ----------------- | -------- | ------------------------------- |
| `id`              | `string` | Unique id of the template       |
| `creativeIntent?` | `string` | Creative intent of the template |

#### `PrintQualityCheckOptions`

The options to pass into the print quality check..

| Name       | Type                                         | Description                                                           |
| ---------- | -------------------------------------------- | --------------------------------------------------------------------- |
| `range`    | [`Range`](../addonsdk/addonsdk-constants.md) | The range of the document to run the print quality check on.          |
| `pageIds?` | `string[]`                                   | Id's of the pages. (Only required when the range is `specificPages`). |

#### `PageMetadata`

The metadata of a page.

| Name                 | Type                                |                                                                                                                                                                                                                                                                                                                                                                Description |
| -------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `id`                 | `string`                            |                                                                                                                                                                                                                                                                                                                                                        The id of the page. |
| `title`              | `string`                            |                                                                                                                                                                                                                                                                                                                                                     The title of the page. |
| `size`               | `{ width: number, height: number }` |                                                                                                                                                                                                                                                                                                                                            The size of the page in pixels. |
| `hasPremiumContent`  | `boolean`                           |                                                                                                                                                                                                                                                                                                                    `true` if the page has premium content, `false` if not. |
| `hasTemporalContent` | `boolean`                           |                                                                                                                                                                                                                                                                                                                          `true` if the page has timelines, `false` if not. |
| `pixelsPerInch?`     | `number`                            |                                                                                                                                                                                                                                                                                                                                           The pixels per inch of the page. |
| `isPrintReady?`      | `boolean`                           | Indicates whether the page has passed various internal quality checks to ensure high quality output when printed. While the specifics may change over time, Adobe Express checks for sufficient image resolution and sizes to ensure that a print will be of good quality. If this is `false`, the output may be blurry or of poor quality (based on internal heuristics). |
| `isBlank?`           | `boolean`                           |                                                                                                                                                                                                                                                                                                                                       Indicates whether the page is blank. |
| `templateDetails?`   | `TemplateDetails`                   |                                                                                                                                                                                                                                                                                                                                  The details of the template for the page. |

#### `PageMetadataOptions`

This object is passed as a parameter to the [`getPagesMetadata`](#getpagesmetadata) method and includes the range and optional `pageIds` for which you want to retrieve metadata for.

| Name                 | Type                                                   |                                                           Description |
| -------------------- | ------------------------------------------------------ | --------------------------------------------------------------------: |
| `range`              | [`Range`](../addonsdk/addonsdk-constants.md#constants) |                             Range of the document to get the metadata |
| `pageIds?: string[]` | `string`                                               | Id's of the pages. (Only required when the range is `specificPages`). |

### link()

Retrieves the document link.

#### Signature

 `link(options: LinkOptions): Promise<string | undefined>`

#### Return Value

A resolved `Promise` containing the `link` of the document.

<InlineAlert slots="text" variant="info"/>

A `documentLinkAvailable` event is triggered when the document link is available in the application. You can listen for this event via the [`addOnUISdk.app.on()`](./addonsdk-app.md#on) method.

#### Example

<CodeBlock slots="heading, code" repeat="1" languages="JavaScript" />

#### Usage

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

function setLink(link) { /* ... */ }

addOnUISdk.ready.then(() => setLink(await AddOnSDKAPI.app.document.link("document"));

addOnUISdk.app.on("documentLinkAvailable", data => {
  setLink(data.documentLink);
});
```

## Import Content Methods

### addImage()

Adds an image/gif/Ps/Ai files to the current page.

#### Signature

`addImage(imageBlob: Blob, attributes?: MediaAttributes): Promise<void>`

#### Parameters

| Name          | Type                                  |                                                                              Description |
| ------------- | ------------------------------------- | ---------------------------------------------------------------------------------------: |
| `imageBlob`   | `Blob`                                |                                                            The image to add to the page. |
| `attributes?` | [`MediaAttributes`](#mediaattributes) | Attributes that can be passed when adding image/Ps/Ai files to the page (i.e., `title`). |

#### Return Value

A resolved promise if the image was successfully added to the canvas; otherwise, it will throw an error with the rejected promise.

#### Example Usage

```js
// Add image(blob) to the current page
async function addImageFromBlob(blob) {
  try {
    await document.addImage(blob);
  } catch (error) {
    console.log("Failed to add the image to the page.");
  }
}

// Add image(url) to the current page
async function addImageFromURL(url) {
  try {
    const blob = await fetch(url).then((response) => response.blob());
    await document.addImage(blob);
  } catch (error) {
    console.log("Failed to add the image to the page.");
  }
}
```

<InlineAlert slots="text" variant="info"/>

Refer to the [image requirements](#image-requirements) section for specific details on supported image sizes and GIF handling.

### addAnimatedImage()

Adds an animated image (gif) to the current page.

#### Signature

`addAnimatedImage(imageBlob: Blob, attributes?: MediaAttributes): Promise<void>`

#### Parameters

| Name          | Type                                  |                                                                          Description |
| ------------- | ------------------------------------- | -----------------------------------------------------------------------------------: |
| `imageBlob`   | `Blob`                                |                                                        The image to add to the page. |
| `attributes?` | [`MediaAttributes`](#mediaattributes) | Attributes that can be passed when adding animated gifs to the page (i.e., `title`). |

#### Return Value

A resolved promise if the animated image was successfully added to the canvas; otherwise, it will throw an error with the rejected promise.

#### Example Usage

```js
// Add animated image(blob) to the current page
async function addAnimatedImageFromBlob(blob) {
  try {
    await document.addAnimatedImage(blob);
  } catch (error) {
    console.log("Failed to add the animated image to the page.");
  }
}
```

<InlineAlert slots="text" variant="info"/>

Refer to the [image requirements](#image-requirements) section for specific details on supported image sizes and GIF handling.

### addVideo()

Adds a video to the current page.

#### Signature

`addVideo(videoBlob: Blob): Promise<void>`

#### Parameters

| Name        | Type   |                   Description |
| ----------- | ------ | ----------------------------: |
| `videoBlob` | `Blob` | The video to add to the page. |

#### Example Usage

```js
async function addVideoFromBlob(blob) {
  try {
    await document.addVideo(blob);
  } catch (error) {
    console.log("Failed to add the video to the page.");
  }
}

async function addVideoFromURL(url) {
  try {
    const blob = await fetch(url).then((response) => response.blob());
    await document.addVideo(blob);
  } catch (error) {
    console.log("Failed to add the video to the page.");
  }
}
```

### addAudio()

Adds audio to the current page.

#### Signature

`addAudio(audioBlob: Blob, attributes: MediaAttributes): Promise<void>`

#### Parameters

| Name         | Type                                  |                                                                             Description |
| ------------ | ------------------------------------- | --------------------------------------------------------------------------------------: |
| `audioBlob`  | `Blob`                                |                                                           The audio to add to the page. |
| `attributes` | [`MediaAttributes`](#mediaattributes) | Attributes to pass when adding the audio to the page (ie: `title`, which is mandatory). |

#### Return Value

A resolved promise if the audio was successfully added to the canvas; otherwise will throw an error with the rejected promise.

#### Example Usage

```js
async function addAudioFromBlob(blob) {
  try {
      await document.addAudio(blob, {title: "Jazzy beats", author: "Jazzy"});
  }
  catch(error) {
      console.log("Failed to add the audio to the page.");
  }
}

async function addAudioFromURL(url) {
  try {
      const blob = await fetch(url).then(response => response.blob());
      await document.addAudio(blob, {title: "Jazzy beats", author: "Jazzy"});
  }
  catch(error) {
      console.log("Failed to add the audio to the page.");
  }
```

#### `MediaAttributes`

| Name      | Type     |                               Description |
| --------- | -------- | ----------------------------------------: |
| `title`   | `string` | Media title (mandatory for audio import). |
| `author?` | `string` |                              Media author |

<InlineAlert slots="text" variant="info"/>

Refer to the [import images how-to](../../guides/develop/how_to/use_images.md#import-images-into-the-page) and the [import-images-from-local](/samples.md#import-images-from-local) in the code samples for general importing content examples.

### importPdf()

Imports a PDF as a new Adobe Express document.

<!-- Removed experimental as part of https://git.corp.adobe.com/Horizon/hz/pull/113300 -->

#### Signature

`importPdf(blob: Blob, attributes: MediaAttributes): void;`

#### Parameters

| Name          | Type                                  |                                                                 Description |
| ------------- | ------------------------------------- | --------------------------------------------------------------------------: |
| `blob`        | `Blob`                                |                                                 The PDF to add to the page. |
| `attributes?` | [`MediaAttributes`](#mediaattributes) | Attributes that can be passed when adding PDFs to the page (i.e., `title`). |

#### Return Value

None

#### Example Usage

```js
import AddOnSDKAPI from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Reference to the active document
const { document } = AddOnSDKAPI.app;

const mediaAttributes = { title: "Sample.pdf" };

// Import a PDF. Note this will be imported as a new Adobe Express document.
function importPdf(blob, mediaAttributes) {
  try {
    document.importPdf(blob, mediaAttributes);
  } catch (error) {
    console.log("Failed to import the pdf.");
  }
}

// Import a PDF from a URL. Note this will be imported as a new Adobe Express document.
async function importPdfFrom(url) {
  try {
    const blob = await fetch(url).then((response) => response.blob());
    document.importPdf(blob, { title: "Sample.pdf" });
  } catch (error) {
    console.log("Failed to import the pdf.");
  }
}
```

### importPresentation()

Imports a presentation as a new Adobe Express document. **Note:** Currently Express only supports PowerPoint presentations.

<!--Removed as part of https://git.corp.adobe.com/Horizon/hz/pull/113300 -->

<!-- <InlineAlert slots="text" variant="warning"/> -->

<!-- **IMPORTANT:** This method is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use this method, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../references/manifest/index.md#requirements) section of the `manifest.json`. -->

#### Signature

`importPresentation(blob: Blob, attributes: MediaAttributes): void;`

#### Parameters

| Name          | Type                                  |                                                                           Description |
| ------------- | ------------------------------------- | ------------------------------------------------------------------------------------: |
| `blob`        | `Blob`                                |                             The PowerPoint presentation (`.pptx`) to add to the page. |
| `attributes?` | [`MediaAttributes`](#mediaattributes) | Attributes that can be passed when adding a presentation to the page (i.e., `title`). |

#### Return Value

None

#### Example Usage

```js
import AddOnSDKAPI from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Reference to the active document
const { document } = AddOnSDKAPI.app;

const mediaAttributes = { title: "Sample.pptx" }; // only Pptx is supported by Express

// Import a presentation. Note: this will be imported as a new Adobe Express presentation.
function importPresentation(blob, mediaAttributes) {
  try {
    document.importPresentation(blob, mediaAttributes);
  } catch (error) {
    console.log("Failed to add the presentation to the document.");
  }
}

// Import a powerpoint presentation from a URL. Note: this will be imported as a new Adobe Express presentation.
async function importPresentationFrom(url) {
  try {
    const blob = await fetch(url).then((response) => response.blob());
    document.importPresentation(blob, { title: "Sample.pptx" });
  } catch (error) {
    console.log("Failed to add the presentation to document.");
  }
}
```

### Image requirements

When importing images, the size of the images for all types **except `gif`** images should not exceed **8000px** or **40MB**.

For `gif` images, [the technical requirements are listed here](https://helpx.adobe.com/express/create-and-edit-videos/change-file-formats/import-gif-limits.html) and summarized below for quick reference:

- **Maximum resolution:** 1080px
- **Maximum size:** 10 MB
- **Maximum GIFs per scene:** 7

<InlineAlert slots="header, text1, text2" variant="info"/>

IMPORTANT: Animated GIFs

Both `addImage()` and `addAnimatedImage()` support `gif` file types, however, you should use the `addAnimatedImage()` method when you want to add an _animated GIF_ specifically but note that it is subject to the size criteria listed above. When the criteria aren't met, only the first frame will be added.

If you supply `addImage()` with an animated GIF, only the first frame will be added by default.

\*\* See the [FAQ's](../../guides/faq.md#what-are-the-supported-file-formats-for-imported-content-in-adobe-express) for the specific file formats allowed for imported content.

### Errors

The table below describes the possible error messages that may occur when using the import methods, with a description of the scenario that would cause them to be returned.

&nbsp;

|                                                                      Error Message |                                                                    Error Scenario |
| ---------------------------------------------------------------------------------: | --------------------------------------------------------------------------------: |
|                                                                      Invalid blob. |                                                                  Blob is invalid. |
|                                             Unsupported mime type : `${blob.type}` |                                                             Mime type is invalid. |
| Import image width or height exceed the maximum limit : `${maxSupportedDimension}` | The imported image dimensions exceed the maximum limit if any defined by Express. |
|                Import image size exceed the maximum limit: `${maxSupportedSize}MB` |      The imported image size exceeds the maximum limit if any defined by Express. |
|                                                          No active page available. |                                                       Current page doesn't exist. |

## Export Content Methods

### createRenditions()

Generate renditions of the current page, specific pages or the entire document in a specified format for export.

#### Signature

`createRenditions(renditionOptions: RenditionOptions, renditionIntent?: RenditionIntent): Promise<Rendition[]>`

#### Parameters

| Name               | Type     |                                                  Description |
| ------------------ | -------- | -----------------------------------------------------------: |
| `renditionOptions` | `Object` |              [`RenditionOptions`](#renditionoptions) object. |
| `renditionIntent`  | `string` | [`RenditionIntent`](./addonsdk-constants.md) constant value. |

**NOTE:** The default value for `renditionIntent` is `export`. If it's set to `preview`, it also requires the `renditionPreview` flag to be set to `true` in the [manifest `requirements`](../manifest/index.md#requirements) section. Additionally, when implementing the premium content flows where you present a dialog or option to allow the user to upgrade, you must be sure to also include the following permissions in the [`sandbox`](../../references/manifest/index.md#entrypointspermissionssandbox) attribute of your `manifest.json` to allow the Adobe Express pricing page to load properly:

```json
"permissions": {
    "sandbox": ["allow-popups-to-escape-sandbox", "allow-popups", "allow-downloads"]
}
```

Refer to the [manage premium content how-to](../../guides/develop/how_to/premium_content.md) for more specific details on options for handling the export of premium content.

#### `RenditionOptions`

| Name       | Type       |                                                                                  Description |
| ---------- | ---------- | -------------------------------------------------------------------------------------------: |
| `range`    | `string`   |                                           [`Range`](./addonsdk-constants.md) constant value. |
| `format`   | `string`   |                                 [`RenditionFormat`](./addonsdk-constants.md) constant value. |
| `pageIds?` | `string[]` | Id's of the pages (only required if the range is [`specificPages`](./addonsdk-constants.md)) |

#### `JpgRenditionOptions`

Extends the [`RenditionOptions`](#renditionoptions) object and adds the following additional options for `jpg` renditions:

| Name                                      | Type                                |                                                                                                                                                                            Description |
| ----------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `backgroundColor?`                        | `number`                            | Integer in 0xRRGGBB format of the background color you wish to sit behind any transparent areas. By default it is derived from the entity for which the rendition needs to be created. |
| `quality?`                                | `number`                            |                                                                                                                    A number between 0 and 1, indicating image quality. Default is 1.0. |
| [`requestedSize?`](#requested-size-notes) | `{width?: number; height?: number}` |                                                                                                                                                            Requested size (in pixels). |

#### `PngRenditionOptions`

Extends the [`RenditionOptions`](#renditionoptions) object and adds the following additional options for `png` renditions:

| Name                                      | Type                                |                                                                                                                                                                            Description |
| ----------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `backgroundColor?`                        | `number`                            | Integer in 0xRRGGBB format of the background color you wish to sit behind any transparent areas. By default it is derived from the entity for which the rendition needs to be created. |
| [`requestedSize?`](#requested-size-notes) | `{width?: number; height?: number}` |                                                                                                                                                            Requested size (in pixels). |

#### Requested Size Notes

- The supported size is from 1 x 1 to width x height.
- Aspect ratio is maintained while scaling the rendition based on the requested size.
- Up-scaling is currently not supported.
- If the requested size is invalid, it will be ignored and the original size rendition will be created.
- Some examples of what the actual exported sizes will be, depending on the page size and requested size are in the table below for reference.

| Page Size | Requested Size | Exported Size |
| --------- | -------------- | ------------: |
| 400 x 600 | 200 x 200      |     134 x 200 |
| 400 x 600 | 200 x 400      |     200 x 300 |
| 400 x 600 | 200 x -200     |     400 x 600 |
| 400 x 600 | 800 x 1000     |     400 x 600 |

#### `PdfRenditionOptions`

Extends the [`RenditionOptions`](#renditionoptions) object and adds the following additional options for `pdf` renditions:

| Name         | Type                            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   Description |
| ------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `bleed?`     | [`Bleed`](#bleed)               | Bleed for the page. In printing, bleed is printing that goes beyond the edge of where the sheet will be trimmed. In other words, the bleed is the area to be trimmed off. The parameter is optional, and if left undefined, then no bleed is assumed. If `bleed` is defined, `CropBox` and `TrimBox` will be the size of the Express document, `BleedBox` and `MediaBox` will be equal to each other, and they will expand on all sides (left, top, right, bottom) with the amount/unit specified by `bleed`. |
| `pageBoxes?` | [`PdfPageBoxes`](#pdfpageboxes) |                                                                                                                                                                                                                               Exposes the ability to customize each PDF Page Box (`MediaBox`, `BleedBox`, `CropBox`, `TrimBox`) dimensions by defining how much it should expand on each side beyond the Express document page size. If `pageBoxes` are defined, then `PdfRenditionOptions.bleed` is ignored. |

#### `Bleed`

Represents a _bleed_ for a page. In printing, _bleed_ is printing that goes beyond the edge of where the sheet will be trimmed. In other words, the bleed is the area to be trimmed off. If the value is left undefined, then no bleed will be assumed.

| Name      | Type                                                       |                                      Description |
| --------- | ---------------------------------------------------------- | -----------------------------------------------: |
| `amount?` | `number`                                                   |                        The amount for the bleed. |
| `unit`    | [`BleedUnit`](../addonsdk/addonsdk-constants.md#constants) | The unit in which the bleed amount is expressed. |

#### `PdfPageBoxes`

Represents all of the PDF page boxes (`MediaBox`, `BleedBox`, `CropBox`, `TrimBox`).

| Name        | Type                        | Description |
| ----------- | --------------------------- | ----------: |
| `mediaBox?` | [`PdfPageBox`](#pdfpagebox) |   Media box |
| `bleedBox?` | [`PdfPageBox`](#pdfpagebox) |   Bleed box |
| `cropBox?`  | [`PdfPageBox`](#pdfpagebox) |    Crop box |
| `trimBox?`  | [`PdfPageBox`](#pdfpagebox) |    Trim box |

#### `PdfPageBox`

Represents a PDF page box.

| Name      | Type                                      |       Description |
| --------- | ----------------------------------------- | ----------------: |
| `margins` | [`PdfPageBoxMargins`](#pdfpageboxmargins) | Margins for a box |

#### `PdfPageBoxMargins`

Represents margins for a PDF page box.

| Name      | Type              |   Description |
| --------- | ----------------- | ------------: |
| `top?`    | [`Bleed`](#bleed) |    Top margin |
| `bottom?` | [`Bleed`](#bleed) | Bottom margin |
| `left?`   | [`Bleed`](#bleed) |   Left margin |
| `right?`  | [`Bleed`](#bleed) |  Right margin |

#### `Mp4RenditionOptions`

Extends the [`RenditionOptions`](#renditionoptions) object and adds the following additional options for `mp4` renditions:

| Name                | Type     |                                                        Description |
| ------------------- | -------- | -----------------------------------------------------------------: |
| `format`            | `string` |   [`RenditionFormat.mp4`](./addonsdk-constants.md) constant value. |
| `resolution?`       | `string` |       [`VideoResolution`](./addonsdk-constants.md) constant value. |
| `customResolution?` | `number` | Only required/used if the `resolution` is `VideoResolution.custom` |

#### Return Value

A `Promise` with an array of page `Rendition` objects (see [`PageRendition`](#pagerendition)). The array will contain one item if the `currentPage` range is requested, an array of specific pages when the `specificPages` range is requested, or all pages when the `entireDocument` range is specified. Each rendition returned will contain the `type`, `title`,[metadata for the page](#pagemetadata) and a `blob` of the rendition itself. **Note:** If you requested `PDF` for the format with a larger range than `currentPage`, a single file will be generated which includes the entire range. When the format is `JPG/PNG/MP4`, an array of files will be generated that represents each page.

<CodeBlock slots="heading, code" repeat="2" languages="JavaScript, TypeScript" />

#### JavaScript

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;

// Display preview of all pages in the AddOn UI
async function displayPreview() {
  try {
    const renditionOptions = {
      range: addOnUISdk.constants.Range.entireDocument,
      format: addOnUISdk.constants.RenditionFormat.png,
      backgroundColor: 0x7faa77ff,
    };
    const renditions = await addOnUISdk.app.document.createRenditions(
      renditionOptions,
      addOnUISdk.constants.RenditionIntent.preview
    );
    renditions.forEach((rendition) => {
      const image = document.createElement("img");
      image.src = URL.createObjectURL(rendition.blob);
      document.body.appendChild(image);
    });
  } catch (error) {
    console.log("Failed to create renditions:", error);
  }
}
```

#### TypeScript

```ts
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;

// Display preview of all pages in the AddOn UI
async function displayPreview() {
  try {
    const renditionOptions: PngRenditionOptions = {
      range: Range.entireDocument,
      format: RenditionFormat.png,
      backgroundColor: 0x7faa77ff,
    };
    const renditions = await addOnUISdk.app.document.createRenditions(
      renditionOptions,
      RenditionIntent.preview
    );
    renditions.forEach((rendition) => {
      const image = document.createElement("img");
      image.src = URL.createObjectURL(rendition.blob);
      document.body.appendChild(image);
    });
  } catch (error) {
    console.log("Failed to create renditions:", error);
  }
}
```

#### `Rendition`

A rendition object representing a page in the document, returned from [`createRenditions`](#createrenditions). See

| Name    | Type     |                                Description |
| ------- | -------- | -----------------------------------------: |
| `type?` | `string` | Type of Rendition. Value is always `page`. |
| `blob`  | `Blob`   |              Blob containing the rendition |

#### `PageRendition`

An extension of [`Rendition`](#rendition), returned in the response to [`createRenditions`](#createrenditions). This object **includes everything in [`Rendition`](#rendition)**, as well as:

| Name       | Type                            |                     Description |
| ---------- | ------------------------------- | ------------------------------: |
| `title`    | `string`                        | The page title of the rendition |
| `metadata` | [`PageMetadata`](#pagemetadata) |                   Page metadata |

\*\* See the [FAQs](../../guides/faq.md#what-are-the-supported-mime-typesfile-formats-for-exported-content) for the file formats and mime types supported for exported content.

<InlineAlert slots="text" variant="info"/>

Refer to the [create renditions how-to](../../guides/develop/how_to/create_renditions.md) and the [export-sample](/samples.md) in the code samples for usage examples.

### Errors

The table below describes the possible error messages that may occur when using the export methods, with a description of the scenario that will return them.

&nbsp;

|                                                      Error Message |                                                          Error Scenario |
| -----------------------------------------------------------------: | ----------------------------------------------------------------------: |
|                                  Invalid range: `${options.range}` |                                                 Range value is invalid. |
|                                          No active page available. |               Range is `Range.currentPage` and there is no active page. |
|                  Unsupported rendition format: `${options.format}` |                                        Rendition format is unsupported. |
|             Invalid background color: `${options.backgroundColor}` |                                            Background color is invalid. |
| Invalid quality parameter: `${options.quality} not in range [0,1]` |                                    Quality property is invalid in jpeg. |
|                           No video element in the specified range. |             No video is present in the range when trying to export mp4. |
|                               USER_NOT_ENTITLED_TO_PREMIUM_CONTENT | The user is trying to export premium content but is not entitled to it. |
# addOnUISdk.app.oauth

Provides access to the OAuth API methods needed for implementing the [user authorization with OAuth 2.0 use case](../../guides/develop/how_to/oauth2.md#use-oauth-20). Be sure to check out the [code samples](/samples.md) as well for more extensive examples of using this workflow.

## Methods

### authorize()

Authorize a user using OAuth 2.0 PKCE workflow.

#### Signature

`authorize(request: AuthorizationRequest): Promise<AuthorizationResponse>`

#### Parameters

| Name      | Type     |                                                                                                              Description |
| --------- | -------- | -----------------------------------------------------------------------------------------------------------------------: |
| `request` | `object` | [`AuthorizationRequest`](#authorizationrequest) object payload with parameters to be used in the authorization workflow. |

#### `AuthorizationRequest`

| Name                    |                                Type |                                                                                                                                                                                                                                                                Description |
| ----------------------- | ----------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `authorizationUrl`      |                            `string` |                                                                                                                                                                                                                                        OAuth provider's authorization URL. |
| `clientId`              |                            `string` |                                                                                                                                                                                                        Client identifier of the application created at the OAuth provider. |
| `scope`                 |                            `string` |                                                                                                                                                                                                                                 Scope to control the application's access. |
| `codeChallenge`         |                            `string` |                                                                                                                                                                                                                        Code challenge used in Authorization Code Exchange. |
| `additionalParameters?` |               `Map<string, string>` |                                                                                                                                               Additional parameters, specific to an OAuth provider which are required in the Authorization URL as query string parameters. |
| `windowSize?`           | `{ width: number; height: number }` | The authorization window size in the form of an `object` containing the desired `width` and `height` as a `number`. <br/><br/>**NOTE:** The **minimum** (and **default**) values for `windowSize` are 480 x 480. The **maximum** allowed values are 800 x (screen height). |

#### Return Value

A resolved `Promise` with the [`AuthorizationResponse`](#authorizationresponse) object containing a one-time authorization code which can be used to obtain an access token.

#### `AuthorizationResponse`

| Name          | Type                 |                                                                                                                                                                                                                                                                                                                                                         Description |
| ------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `id`          | `string`             |                                                                                                                                                                                                                                                                                                                    Unique identifier for the authorization request. |
| `code`        | `string`             |                                                                                                                                                                                                                                                        OAuth 2.0 generated authorization code which can be used once to obtain an access token and a refresh token. |
| `redirectUri` | `string`             |                                                                                                                                                                                                   URL where the user is redirected to after authorization. This is the default URL owned by Adobe and it is this URL which needs to be used to obtain access_token. |
| `result`      | `string` or `object` | An [`AuthorizationResult`](#authorizationresult) payload which denotes either success or failure. In the event of a "FAILED" status reported by the OAuth provider during authorization, the value of this property is an `object`, in the form of `{[failure_title]: "failure_description"}`, and for all other statuses the value of `description` is a `string`. |

### authorizeWithOwnRedirect()

Initiate the OAuth 2.0 PKCE authorization workflow by opening the user sign-in window. After authorization, the user is redirected to the add-on developer provided URL.

#### Signature:

`authorizeWithOwnRedirect(request: AuthorizeWithOwnRedirectRequest): Promise<AuthorizationResult>`

#### Parameters

| Name      | Type     |                                                                                                                                    Description |
| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------: |
| `request` | `object` | [`AuthorizeWithOwnRedirectRequest`](#authorizewithownredirectrequest) object payload with parameters to be used in the authorization workflow. |

#### `AuthorizeWithOwnRedirectRequest`

| Name                    |                                Type |                                                                                                                                                                                                                                                                Description |
| ----------------------- | ----------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `authorizationUrl`      |                            `string` |                                                                                                                                                                                                                                        OAuth provider's authorization URL. |
| `clientId`              |                            `string` |                                                                                                                                                                                                        Client identifier of the application created at the OAuth provider. |
| `scope`                 |                            `string` |                                                                                                                                                                                                                                 Scope to control the application's access. |
| `codeChallenge`         |                            `string` |                                                                                                                                                                                                                        Code challenge used in Authorization Code Exchange. |
| `additionalParameters?` |               `Map<string, string>` |                                                                                                                                               Additional parameters, specific to an OAuth provider which are required in the Authorization URL as query string parameters. |
| `windowSize?`           | `{ width: number; height: number }` | The authorization window size in the form of an `object` containing the desired `width` and `height` as a `number`. <br/><br/>**NOTE:** The **minimum** (and **default**) values for `windowSize` are 480 x 480. The **maximum** allowed values are 800 x (screen height). |
| `redirectUri`           |                            `string` |                                                                                                                  URL where the user is redirected to after successful or failed authorization. Hosting and handling redirects to this URL should be managed by the caller. |
| `state`                 |                            `string` |                 A value which is preserved in the request, and replayed back as a query string parameter in the `redirectUri`. Although the primary reason for using the state parameter is to mitigate CSRF attacks, it can also be used to encode any other information. |

#### Return Value

A resolved `Promise` with the [`AuthorizationResult`](#authorizationresult) object, which contains a `status` and a `description`, which will either be a `string` or an `object`. In the event of a `FAILED` status reported by the OAuth provider during authorization, the value of this property is an `object`, in the form of `{[failure_title]: "failure_description"}`, and for all other statuses, the value of `description` is a `string`.

#### `AuthorizationResult`

| Name          |                  Type |                                                                                                                                                                                                                                                                                                                               Description |
| ------------- | --------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `status`      | `AuthorizationStatus` |                                                                                                                                                                                                                                                                     Status representing success or failure in the authorization workflow. |
| `description` |  `string` or `object` | Description about the success or failure in the authorization workflow In the event of a "FAILED" status reported by the OAuth provider during authorization, the value of this property is an `object`, in the form of `{[failure_title]: "failure_description"}`. While for all other statuses the value of this property is a `string` |

#### `AuthorizationStatus`

Each of the statuses returned below is the exact name as a string (ie: SUCCESS = "SUCCESS")

| Name          | Type     |                                                                                                             Description |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------: |
| SUCCESS       | `string` |                            Successful authorization this is the expected result for the [Authorize](#authorize) method) |
| POPUP_OPENED  | `string` | The popup was opened (this is the expected result for the [AuthorizeWithOwnRedirect](#authorizewithownredirect) method) |
| POPUP_BLOCKED | `string` |      The popup was blocked. (Add `allow-popups` permission to your [manifest.json](../manifest/) `sandbox` permissions) |
| POPUP_TIMEOUT | `string` |                                                                                                    The popup timed out. |
| FAILED        | `string` |                                                                                       The authorization workflow failed |

## Errors

The table below describes the possible error statuses returned when using the OAuth API, with a description of the scenario that will return them.

<br/>

|  Error Status |                                                                     Description |
| ------------: | ------------------------------------------------------------------------------: |
| POPUP_BLOCKED |                                       The window for authorization was blocked. |
| POPUP_TIMEOUT |                                     The window for authorization was timed out. |
|        FAILED | &lt;Failure object returned by the OAuth provider when authorization fails.&gt; |
# addOnUISdk.app.ui

Provides you with UI related values from the Adobe Express host application where the add-on is running, so you can do things such as detect the [current locale](../../guides/develop/how_to/theme_locale.md#detecting-locale-supported-locales-and-format) or [theme](../../guides/develop/how_to/theme_locale.md#detecting-theme) in use to update your add-on user interface accordingly.

## Properties

### theme

Access the theme currently set in Adobe Express. This value is accessed via the `AddOnSdk.app.ui` object, so you should ensure you only access this object after the AddOnSdk is initialized (via the `ready`).

#### Values

A `string` containing the current theme value. Currently **"light"** is the only theme supported.

#### Example Usage

```js
addOnUISdk.ready.then(async () => {
  console.log(addOnUISdk.app.ui.theme); // output is "light"
});
```

### locale

Access the locale currently set in Adobe Express. This value is accessed via the `addOnUISdk.app.ui` object, so you should ensure you only access this object after the `addOnUISdk` is initialized (via the `addOnUISdk.ready`).

#### Values

A `string` containing the current locale value. Current locale could be one of:

```json
[
  "cy-GB",
  "da-DK",
  "de-DE",
  "en-US",
  "es-ES",
  "fi-FI",
  "fr-FR",
  "it-IT",
  "ja-JP",
  "ko-KR",
  "nb-NO",
  "nl-NL",
  "pt-BR",
  "sv-SE",
  "zh-Hans-CN",
  "zh-Hant-TW",
  "zz-ZZ"
]
```

#### Example Usage

```js
addOnUISdk.ready.then(async () => {
  console.log(addOnUISdk.app.ui.locale); // output "es-ES"
});
```

### locales

<!-- **`locales: string[]`**<br/> -->

Access all locales currently supported in Adobe Express. This value is accessed via the `addOnUISdk.app.ui` object, so you should ensure you only access this object after the AddOnSdk is initialized (via the `addOnUISdk.ready`).

#### Values

A `string` array containing the supported locales:

```json
locales:
    ['cy-GB', 'da-DK', 'de-DE', 'en-US', 'es-ES', 'fi-FI', 'fr-FR', 'it-IT', 'ja-JP', 'ko-KR', 'nb-NO', 'nl-NL', 'pt-BR', 'sv-SE', 'zh-Hans-CN', 'zh-Hant-TW', 'zz-ZZ']
```

#### Example Usage

```js
addOnUISdk.ready.then(async () => {
  console.log(JSON.stringify(addOnUISdk.app.ui.locales));
  // output is ["cy-GB","da-DK","de-DE","en-US","es-ES","fi-FI","fr-FR","it-IT","ja-JP","ko-KR","nb-NO","nl-NL","pt-BR","sv-SE","zh-Hans-CN","zh-Hant-TW","zz-ZZ"]
});
```

### format

Access the regional format currently set in Adobe Express to display dates, times, numbers, etc. This value is accessed via the `addOnUISdk.app.ui` object, so you should only access this object after the `addOnUISdk` is initialized (via the `addOnUISdk.ready`).

#### Values

A `string` containing the current format value. Current regional format could be one of:

```json
[
  "ms-MY",
  "cs-CZ",
  "cy-GB",
  "da-DK",
  "de-DE",
  "de-LU",
  "de-AT",
  "de-CH",
  "et-EE",
  "en-AU",
  "en-CA",
  "en-GB",
  "en-HK",
  "en-IN",
  "en-IE",
  "en-IL",
  "en-NZ",
  "en-SG",
  "en-ZA",
  "en-US",
  "es-AR",
  "es-CL",
  "es-CO",
  "es-CR",
  "es-EC",
  "es-ES",
  "es-GT",
  "es-419",
  "es-MX",
  "es-PE",
  "es-PR",
  "fr-BE",
  "fr-CA",
  "fr-FR",
  "fr-LU",
  "fr-CH",
  "hr-HR",
  "id-ID",
  "it-IT",
  "it-CH",
  "lv-LV",
  "lt-LT",
  "hu-HU",
  "nl-BE",
  "nl-NL",
  "nb-NO",
  "pl-PL",
  "pt-BR",
  "pt-PT",
  "ro-RO",
  "sk-SK",
  "sl-SI",
  "sr-Latn-RS",
  "fi-FI",
  "sv-SE",
  "vi-VN",
  "tr-TR",
  "el-GR",
  "bg-BG",
  "ru-RU",
  "uk-UA",
  "he-IL",
  "ar-AE",
  "ar-KW",
  "ar-SA",
  "ar-QA",
  "ar-EG",
  "ne-NP",
  "mr-IN",
  "hi-IN",
  "bn-IN",
  "ta-IN",
  "te-IN",
  "th-TH",
  "ko-KR",
  "zh-Hant-HK",
  "ja-JP",
  "zh-Hans-CN",
  "zh-Hant-TW"
]
```

#### Example Usage

```js
addOnUISdk.ready.then(async () => {
  console.log(addOnUISdk.app.ui.format); // output "en-GB"
});
```

## Methods

### openEditorPanel

Programmatically open the Editor panel in Adobe Express. When sub-tabs are available, this method can target them, as well as pre-populate the Search field.

#### Signature

`openEditorPanel(panel: EditorPanel, action?: PanelAction): void;`

#### Parameters

| Name      | Type     |                                              Description |
| --------- | -------- | -------------------------------------------------------: |
| `panel`   | `string` | [`EditorPanel`](./addonsdk-constants.md) constant value. |
| `action?` | `Object` |                    [`PanelAction`](#panelaction) object. |

#### `PanelAction`

| Name   | Type     |                                                  Description |
| ------ | -------- | -----------------------------------------------------------: |
| `type` | `string` | [`PanelActionType`](./addonsdk-constants.md) constant value. |

#### `SearchAction`

Extends the [`PanelAction`](#panelaction) object and adds the following options for the Search action:

| Name           | Type     |                                                         Description |
| -------------- | -------- | ------------------------------------------------------------------: |
| `type`         | `string` | [`PanelActionType.search`](./addonsdk-constants.md) constant value. |
| `searchString` | `string` |                            Query used to perform the Search action. |

#### `NavigateAction`

Extends the [`PanelAction`](#panelaction) object and adds the following options for the Navigation action:

| Name            | Type     |                                                                                         Description |
| --------------- | -------- | --------------------------------------------------------------------------------------------------: |
| `type`          | `string` |                               [`PanelActionType.navigate`](./addonsdk-constants.md) constant value. |
| `tab?`          | `string` | [`ElementsTabs`](./addonsdk-constants.md) or [`MediaTabs`](./addonsdk-constants.md) constant values |
| `collectionId?` | `string` |                                                 collectionId of the asset collection to navigate to |

#### Actions Notes

Actions are currently not supported on every Editor panel. Please find the supported actions for each panel below:

| Action                 |                                     Supported panels |
| ---------------------- | ---------------------------------------------------: |
| Search                 | Templates, Media, Elements, Text, Your stuff, Search |
| Navigate to Collection |                     Templates, Media, Elements, Text |
| Navigate to Tab        |                                      Media, Elements |

Both Collection and Tab navigation can be executed in combination.

#### Example usage

<CodeBlock slots="heading, code" repeat="2" languages="JavaScript, TypeScript" />

#### JavaScript

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
const { constants } = addOnUISdk;
const { PanelActionType, EditorPanel } = constants;

addOnUISdk.ready.then(() => {
  const action = {
    type: PanelActionType.search,
    searchString: "test",
  };
  addOnUISdk.app.ui.openEditorPanel(EditorPanel.templates, action);
});

// Navigate to collection
addOnUISdk.ready.then(() => {
  const action = {
    type: PanelActionType.navigate,
    collectionId: "urn:aaid:sc:VA6C2:cd6aa706-12f2-525b-9500-3d23bc663882",
  };
  addOnUISdk.app.ui.openEditorPanel(EditorPanel.templates, action);
});

// Navigate to tab
addOnUISdk.ready.then(() => {
  const action: NavigateAction = {
    type: PanelActionType.navigate,
    tab: "photos",
  };
  addOnUISdk.app.ui.openEditorPanel(EditorPanel.media, action);
});

// Navigate to tab + collection
addOnUISdk.ready.then(() => {
  const action: NavigateAction = {
    type: PanelActionType.navigate,
    tab: "photos",
    collectionId: "urn:aaid:sc:VA6C2:cd6aa706-12f2-525b-9500-3d23bc663882",
  };
  addOnUISdk.app.ui.openEditorPanel(EditorPanel.media, action);
});
```

#### TypeScript

```ts
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
const { constants } = addOnUISdk;
const { PanelActionType, EditorPanel } = constants;

addOnUISdk.ready.then(() => {
  const action: SearchAction = {
    type: PanelActionType.search,
    searchString: "test",
  };
  addOnUISdk.app.ui.openEditorPanel(EditorPanel.templates, action);
});

// Navigate to collection
addOnUISdk.ready.then(() => {
  const action: NavigateAction = {
    type: PanelActionType.navigate,
    collectionId: "urn:aaid:sc:VA6C2:cd6aa706-12f2-525b-9500-3d23bc663882",
  };
  addOnUISdk.app.ui.openEditorPanel(EditorPanel.templates, action);
});

// Navigate to tab
addOnUISdk.ready.then(() => {
  const action: NavigateAction = {
    type: PanelActionType.navigate,
    tab: "photos",
  };
  addOnUISdk.app.ui.openEditorPanel(EditorPanel.media, action);
});

// Navigate to tab + collection
addOnUISdk.ready.then(() => {
  const action: NavigateAction = {
    type: PanelActionType.navigate,
    tab: "photos",
    collectionId: "urn:aaid:sc:VA6C2:cd6aa706-12f2-525b-9500-3d23bc663882",
  };
  addOnUISdk.app.ui.openEditorPanel(EditorPanel.media, action);
});
```

## Events

### themechange

**`themechange: string`**<br/>
The "themechange" event is fired when the user changes the UI theme in Adobe Express. It's used with the [`addOnUISdk.app.on`](../addonsdk/addonsdk-app.md) function.

#### Parameters

N/A

#### Return Value

N/A

#### Example Usage

```js
addOnUISdk.app.on("themechange", (data) => {
  applyTheme(data.theme);
});
```

<InlineAlert slots="text" variant="success"/>

Please see the **swc** sample provided in the [code samples](../../samples.md) within the **contributed** folder as a reference for how to use the `theme` in your own add-on.

### localechange

**`localechange: string`**<br/>
The "localechange" event is fired when the user changes the UI locale in Adobe Express. It's used with the [`addOnUISdk.app.on`](../addonsdk/addonsdk-app.md) function.

#### Parameters

N/A

#### Return Value

N/A

#### Example Usage

```js
addOnUISdk.app.on("localechange", (data) => {
  applyTheme(data.locale);
});
```

### formatchange

**`formatchange: string`**<br/>
The "formatchange" event is fired when the user changes the UI format in Adobe Express. It's used with the [`addOnUISdk.app.on`](../addonsdk/addonsdk-app.md) function.

#### Parameters

N/A

#### Return Value

N/A

#### Example Usage

```js
addOnUISdk.app.on("formatchange", (data) => {
  console.log(data.format);
});
```
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: SDK Reference
description: The Adobe Express add-on SDK Reference.
contributors:
  - https://github.com/hollyschinsky
---

# Add-on UI SDK Reference

## Overview

This reference is provided to outline the interfaces, methods, properties and events that support the [add-on UI SDK features](#features-supported-by-the-sdk). It begins with an introduction to the core `addOnUiSdk` module, which provides access to all of the interfaces available to use in the iframe where your add-on is running. Import this module to use it for accessing all of the API's that allow you to implement features like those outlined in the next section.

## Features Supported by the SDK

- [Importing Content](../../guides/develop/how_to/use_images.md)
- [Exporting Content](../../guides/develop/how_to/create_renditions.md)
- [Accessing Content](../../guides/develop/how_to/group_elements.md)
- [Drag & Drop Behavior](../../guides/develop/how_to/drag_and_drop.md)
- [Authorization with OAuth 2.0](../../guides/develop/how_to/oauth2.md)
- [Client-side Storage Access](../../guides/develop/how_to/local_data_management.md)
- [Modal Dialogs](../../guides/develop/how_to/modal_dialogs.md)
- [Locale Detection](../../guides/develop/how_to/theme_locale.md#detecting-locale-supported-locales-and-format)
- [Theme Detection](../../guides/develop/how_to/theme_locale.md#detecting-theme)
- [Access to the Manifest](/references/addonsdk/instance-manifest.md)
- [Access to the Document information](/references/addonsdk/app-document.md)

<InlineAlert slots="text" variant="success"/>

See the [implementing common use cases page](../../guides/develop/) for details and examples of how to add the features above.

<InlineAlert slots="header, text1, text2, text3, text4" variant="success"/>

# SDK vs API

The distinction between an SDK and an API can be a bit blurry and can depend on the specific context. However, here's a general overview of the differences between an SDK and an API:

**SDK** (Software Development Kit) - a collection of software development tools and libraries that developers can use to create applications for a specific platform or system. An SDK typically includes an API, documentation, code samples, and other resources that developers need to build applications.

**API** (Application Programming Interface) - a set of rules and protocols that developers can use to interact with a platform.

In general, an SDK provides a more complete set of tools and resources for developers than an API alone. An SDK may include an API, but it also includes other tools and resources that can help developers build applications more easily. However, the terms SDK and API are often used interchangeably, and the specific definitions can vary depending on the context.

**Note:** an `interface` can also be considered an `object` in terms of this reference. You can traverse the `addOnUISdk` interfaces/objects (ie: `app`,`instance`) etc in the left navigation to learn more.

## Importing the addOnUISdk for Use

The add-on SDK is available as a hosted JavaScript module on the Adobe CDN. It's referenced with an `import` statement in either an HTML `<script>` tag or in the list of `import` statements in the JavaScript source. However, you don't need to worry about adding this reference if you used the CLI to create your add-on project, since **it will already be imported for you**, and the location it was placed will depend on the `template` you chose. The following sections show how it's imported into different file types for reference.

#### Import into HTML file

To use the SDK from an HTML file, simply include a link to it in a `<script>` tag with the `type=module` attribute on it to ensure everything is initialized properly.

```js
<body>
    Hello World!
    <script type="module">
        import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
        addOnUISdk.ready.then(async () => {
            console.log("addOnUISdk is ready for use.");
        });
    </script>
</body>
```

<InlineAlert slots="text" variant="success"/>

**TIP:** Placing your `<script>` tag just before the closing `<body>` tag helps reduce the page loading time.

#### Import into JavaScript/TypeScript file

The SDK can be referenced in `.js/.jsx/.ts/.tsx` source files by adding it to the list of imports as a default module reference, such as in the following:

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
```

**Note:** if you created your add-on project with the CLI based on the `typescript` or `typescript-react` templates, you will automatically get a types definition file named `add-on-ui-sdk.d.ts` generated in your project `src` for you. This file contains the following exports, and allows you to take advantage of type checking and auto-completion features while developing with the Add-on SDK in your IDE.

```ts
declare module "https://new.express.adobe.com/static/add-on-sdk/sdk.js" {
  export * from "@adobe-ccwebext/ccweb-add-on-sdk-types";
  export { default } from "@adobe-ccwebext/ccweb-add-on-sdk-types";
}
```

See the [typescript definitions section](../../guides/develop/frameworks-libraries-bundling.md#typescript-definitions) in the developer guides as well for more details.

## addOnUISdk Properties

The following properties can be accessed from the `addOnUISdk` object after it has been imported.<br/><br/>

<table columnWidths="20,30,15,35" class="spectrum-Table spectrum-Table--sizeM" css="
    background-color:lavender;
    tbody {
      background-color:white;
    }">
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-headCell"><p><strong>Attribute</strong></p></td>
    <td class="spectrum-Table-headCell"><p><strong>Name</strong></p></td>
    <td class="spectrum-Table-headCell"><p><strong>Type</strong></p></td>
    <td class="spectrum-Table-headCell"><p><strong>Description</strong></p></td>
</tr>
<tbody class="spectrum-Table-body">
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>readonly</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>addOnUISdk.app</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>object</pre></p></td>
    <td class="spectrum-Table-cell"><p>Provides access to the host application (Adobe Express)</p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>readonly</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>addOnUISdk.instance</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>object</pre></p></td>
    <td class="spectrum-Table-cell"><p>The currently running add-on instance.</p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>readonly</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>addOnUISdk.ready</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>Promise</pre></p></td>
    <td class="spectrum-Table-cell"><p>Indicates the addOnUISdk object has been initialized and you can start accessing the APIs. Register a call back with <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then">Promise.then</a> or <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await">await this promise</a>.</p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre></pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>addOnUISdk.constants</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>object</pre></p></td>
    <td class="spectrum-Table-cell"><p>A set of constants used throughout the add-on SDK.</p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><pre>readonly</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>addOnUISdk.apiVersion</pre></p></td>
    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
    <td class="spectrum-Table-cell"><p>The current version of the add-on SDK running.</p></td>
</tr>
</tbody>
</table>

## addOnUISdk Errors

The table below describes the possible error messages that may occur when using the core `addOnUISdk` object, with a description of the scenario that will return them.

<br/>

|                                                            Error Message |                                                      Error Scenario |
| -----------------------------------------------------------------------: | ------------------------------------------------------------------: |
|        Invalid `${propertyName}` property. SDK is not fully initialized. | When an add-on tries to use the SDK before it is fully initialized. |
| Failed to initialize Addon SDK. Unsupported API version: `${apiVersion}` |                                         API version is unsupported. |
# addOnUISdk.instance.clientStorage

The `clientStorage` object provides a reference to Client Storage in the currently running add-on. Client Storage allows you to store, retrieve, and delete persistent data in the user's current browser.

Client Storage is similar to using `Window.localStorage`, but is asynchronous, supports multiple datatypes, (i.e., objects, arrays, strings, numbers, booleans, `null`, `undefined` and `Uint8Array`) and has a larger storage limit. Each add-on can store up to 10 mb of data in `ClientStorage`, per user. Any data additions over 10 mb will throw a quota error. However, an add-on developer can write code to delete old data so that new data can be added. See the [Storing and Retrieving Client Side Data](../../guides/develop/how_to/local_data_management.md) for more details.

<InlineAlert slots="text1, text2" variant="info"/>

Since the data in Client Storage is stored in the user's current browser, any actions that clear the browser cache, such as clearing browsing history or deleting cookies, will also clear all of the data stored in Client Storage. It's important to keep this in mind when designing your add-on, as any important data that needs to persist beyond a user's current browsing session should be stored elsewhere, such as on a server or in a database.

Additionally, you should always provide a way for users to delete or clear any data stored in Client Storage within your add-on, in case they want to remove any sensitive or unwanted data.

## Methods

### getItem()

**`async getItem(key: string): Promise<unknown | undefined>`**<br/>
An asynchronous method to retrieve a value from Client Storage for a given key. If no value has been stored for that key, this function will return `undefined`.

#### Parameters

| Name | Type     |                        Description |
| ---- | -------- | ---------------------------------: |
| key  | `string` | The key to retrieve the value for. |

#### Returns

`Promise` or `undefined` if no value has been stored for that key.

#### Example Usage

```js
async function getData(key) {
  try {
    return await clientStorage.getItem(key);
  } catch (error) {
    console.log("Failed to get the value from the ClientStorage.");
  }
}
```

### setItem()

**`async setItem(key: string, value: any): Promise<void>;`**<br/>
Store a value in Client Storage with the given key. The returned promise will resolve if storage is successful, or reject with an error message if storage failed. The value can be any of multiple data types, such as `object`, `string`, array, `number`, `boolean`, `null`, `undefined` and `Uint8Array`.

#### Parameters

| Name  | Type     |                            Description |
| ----- | -------- | -------------------------------------: |
| key   | `string` | The key to reference the value stored. |
| value | `any`    |        The value to store for the key. |

#### Returns

`Promise` or `undefined` if no value has been stored for that key.

#### Example Usage

```js
async function setData(key, value) {
  try {
    await clientStorage.setItem(key, value);
  } catch (error) {
    console.log("Failed to set the value to the ClientStorage.");
  }
}
```

### removeItem()

**`async removeItem(key: string): Promise<void>`**<br/>
Remove the stored key/value pair from Client Storage for the given key. If no such key is stored, this function will return normally, but will otherwise do nothing.

#### Parameters

| Name | Type     |                                                             Description |
| ---- | -------- | ----------------------------------------------------------------------: |
| key  | `string` | The key indicating which specific key/value pair to remove from storage |

#### Returns

`Promise` or nothing if the key is not found.

#### Example Usage

```js
async function removeData(key) {
  try {
    await clientStorage.removeItem(key);
  } catch (error) {
    console.log("Failed to delete the key/value pair from ClientStorage.");
  }
}
```

### clear()

**`clear(): Promise<void>`**<br/>
Delete all data present in ClientStorage for this add-on.

#### Parameters

None

#### Returns

`Promise` or returns normally when there's nothing to clear.

#### Example Usage

```js
async function clearData() {
  try {
    await clientStorage.clear();
  } catch (error) {
    console.log("Failed to clear the data from the ClientStorage.");
  }
}
```

### keys()

**`async keys(): Promise<string[]>`**<br/>
Retrieve a list of all keys in Client Storage. Use this to enumerate the full contents of the Client Storage for the add-on.

#### Parameters

None

#### Returns

`Promise` with an array of the keys found when the promise resolves (all type `string`).

#### Example Usage

```js
async function getKeys() {
  try {
    const keys = await clientStorage.keys();
    keys.forEach((key) => console.log(key));
  } catch (error) {
    console.log("Failed to get the keys from the ClientStorage.");
  }
}
```

<InlineAlert slots="text" variant="info"/>

Be sure to check out the [Storing and Retrieving Client Side Data](../../guides/develop/how_to/local_data_management.md) for more details about using Client Storage, as well as the [**use-client-storage** sample](/samples.md) for a more complete example of implementing it in an add-on.

## Errors

The table below describes the possible error messages that may occur when using the Client Storage API, with a description of the scenario that will return them.

<br/>

|                                  Error Message |                              Error Scenario |
| ---------------------------------------------: | ------------------------------------------: |
| Quota exceeded. Delete some data to store more | Returned when the quota limit is exhausted. |
# addOnUISdk.instance.manifest

The `manifest` object provides access to the `manifest.json` file entries of the add-on.

## Type

`object` (specific type `Record`)

Please see the [Manifest Schema Reference](../manifest/) for the whole list of properties and types that can be specified in the `manifest.json` for your add-on.

## Usage

Below is an example of using the `manifest` object, along with the expected output.

<CodeBlock slots="heading, code" repeat="2" languages="JavaScript" />

### Example

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(() => {  
  console.log(JSON.stringify(addOnUISdk.instance.manifest));  

  console.log("Name: " + manifest["name"]);
  console.log("Test ID " + manifest["testId"]);                
  console.log("Version " + manifest["version"]);
  console.log("Manifest Version " + manifest["manifestVersion"]);
  for (const app of manifest["requirements"]["apps"]) {
      console.log("Requirements -> Apps " + JSON.stringify(app));
  }
  for (const entryPoint of manifest["entryPoints"]) {
      console.log("Entry Point Type " + entryPoint["type"]);
      console.log("Entry Point ID " + entryPoint["id"]);
      console.log("Entry Point main " + entryPoint["main"]);    
}
});
```

### Output

```js
{"testId":"08f4469f-7999-458b-9ef9-b1bd043cbdca","name":"Add On Api Sampler","version":"1.0.0","manifestVersion":2,"requirements":{"apps":[{"name":"Express","apiVersion":1}]},"entryPoints":[{"type":"panel","id":"panel1","main":"https://localhost:5241/08f4469f-7999-458b-9ef9-b1bd043cbdca/index.html"}]}

Name: Add On Api Sampler
Test ID 08f4469f-7999-458b-9ef9-b1bd043cbdca
Version 1.0.0
Manifest Version 2
Requirements -> Apps {"name":"Express","apiVersion":1}
Entry Point Type panel
Entry Point ID panel1
Entry Point main https://localhost:5241/08f4469f-7999-458b-9ef9-b1bd043cbdca/index.html
```
# addOnUISdk.instance.runtime

Represents the runtime of the current add-on.

## Properties

### `type`

The [RuntimeType](addonsdk-constants.md) constant representing the entrypoint creating this backend object (ie: `"panel"`, `"dialog"` or `"documentSandbox"`).

### [`Dialog`](../addonsdk/runtime-dialog.md)

(Optional) When the `RuntimeType` is `"dialog"`, this object will contain the reference to the [modal dialog](runtime-dialog.md) the add-on invoked, and can be used to programmatically close the dialog and send results back to the caller. Will be `undefined` when no modal dialog is present. Check out the [modal dialogs use case examples](../../guides/develop/how_to/modal_dialogs.md) for more details on using dialogs, as well as the related [`showModalDialog` method](../addonsdk/addonsdk-app.md#showmodaldialog).

## Methods

The following methods allow you to communicate bidirectionally between the add-on running in the iframe and the [document sandbox](../document-sandbox/) environments.

### exposeApi()

Use this method to expose an API from your UI code running in the iframe to another runtime (ie: the [document sandbox code](../document-sandbox/) defined in your `code.js` for instance).

#### Signature

`exposeApi<T>(obj: T): void`

#### Parameters

| Name  | Type     |                                                                                                                                                                                                                                       Description |
| ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `obj` | `object` | The concrete object/class instance to expose to other runtimes. This method call is allowed only once. Subsequent calls are ignored. **Note**: you cannot expose entire classes from one runtime and create an instance of that class in another. |

### apiProxy()

Requests a promise-based proxy object from another runtime to be used to call the APIs exposed by that other runtime via the `exposeApi` method.

#### Signature

`async apiProxy(runtimeType: RuntimeType): Promise<Remote<unknown>>`

#### Parameters

| Name          | Type          |                                                                                                                                                                                                                                                    Description |
| ------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `runtimeType` | `RuntimeType` | The runtime type to create the proxy object from (ie: "documentSandbox" for instance, which maps to the code referenced in the [`documentSandbox` entryPoint](../document-sandbox/index.md#document-sandbox-entry-point) in your add-on's `manifest.js` file). |

#### Return

A promise which resolves to an API proxy object exposed by the desired runtime as soon as the other runtime is finished initializing.

**Note:** Calling the method again for the same runtime type will return a new proxy object without any behavior difference.

#### Example Usage

```js
addOnUISdk.ready.then(async () => {
  console.log("addOnUISdk is ready for use.");
  const { runtime } = addOnUISdk.instance;

  let createShapesButton = document.getElementById("createShapesButton");
  createShapesButton.addEventListener("click", async (e) => {
    const sandboxProxy = await runtime.apiProxy("documentSandbox");
    try {
      let result = await sandboxProxy.createShapes();
      console.log(result);
    } catch (exc) {
      console.error(exc.message, exc.stack);
    }
  });
});
```
# addOnUISdk.instance.runtime.dialog

Represents the modal dialog presented to the user. This object can be used to manage the dialog, like closing it and sending results to the caller. Check out the [modal dialogs use case examples](../../guides/develop/how_to/modal_dialogs.md) for more details on using dialogs, as well as the related [`showModalDialog` method](../addonsdk/addonsdk-app.md#showmodaldialog).

## Methods

### close()

**`close(result?: unknown): void`**<br/>
Closes the modal dialog and posts the result back to the dialog invoker.

#### Parameters

| Name      | Type           |                                         Description |
| --------- | -------------- | --------------------------------------------------: |
| `result?` | `unknown<any>` | An optional result to return to the dialog invoker. |

#### Returns

An optional result of a user-defined type.

#### Example Usage

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;

closeButton.onsubmit = () => {
  // User cancelled the operation, close the dialog with no result
  addOnUISdk.instance.runtime.dialog.close();
};

createButton.onsubmit = () => {
  // user has selected a design - close the dialog & report the selection details as the result back to the caller.
  addOnUISdk.instance.runtime.dialog.close({
    selectedDesign: "grid-layout",
  });
};
```
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
  - AddOnSdk
title: Changelog
description: Contains a running log of changes to the add-on documentation, SDK, CLI, etc.
contributors:
  - https://github.com/hollyschinsky
  - https://github.com/undavide
  - https://github.com/nimithajalal
---

# Changelog

## 2025-04-22

### Updated

- The [Code Playground](../guides/getting_started/code_playground.md) documentation has been updated with details about the new [Script Mode](../guides/getting_started/code_playground.md#how-to-use-script-mode) and [Local Persistence](../guides/getting_started/code_playground.md#saving-your-work) features, as well as additional details around existing features. The updates include:

  - New sections explaining Script Mode and Add-on Mode.
  - Detailed descriptions of the different tabs available in the Add-on mode and what type of code belongs in each.
  - Information about local persistence and session management.
  - Additional guidance on transitioning code between modes.
  - New keyboard shortcuts for improved productivity.

## 2025-04-10

### Added

- New [`link()`](../references/addonsdk/app-document.md#link) method added to the `AddOnUISdk.app.document` reference and [Document Metadata How-to Guide](../guides/develop/how_to/document_metadata.md). This method retrieves the document link and triggers a `documentLinkAvailable` event when the link is available.
- New [vue-starter](../samples.md#vue-starter) sample add-on to help developers get started using Vue.js in their add-ons.
- Fixes `fromRGB()` method reference in the [Using Color How-to](../guides/develop/how_to/use_color.md).

## 2025-04-03

### Added

- A new [`hasUnavailableFonts()`](./document-sandbox/document-apis/classes/TextContentModel.md#hasunavailablefonts) method is added to [`TextContentModel`](./document-sandbox/document-apis/classes/TextContentModel.md) class, which returns true if the text contains any fonts unavailable to the current user.

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** The [`hasUnavailableFonts()`](./document-sandbox/document-apis/classes/TextContentModel.md#hasunavailablefonts) is currently **_experimental only_** and should not be used in any add-ons you will be distributing until it has been declared stable. To use this method, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../references/manifest/index.md#requirements) section of the `manifest.json`.

### Updated

The CLI has been updated with the following package versions:

- `@adobe/ccweb-add-on-manifest`: 3.0.0
- `@adobe/create-ccweb-add-on`: 3.0.0
- `@adobe/ccweb-add-on-scaffolder`: 3.0.0
- `@adobe/ccweb-add-on-analytics`: 3.0.0
- `@adobe/ccweb-add-on-core`: 3.0.0
- `@adobe/ccweb-add-on-scripts`: 3.0.0
- `@adobe/ccweb-add-on-ssl`: 3.0.0
- `@adobe/ccweb-add-on-sdk-types`: 1.14.0

**IMPORTANT:** As a result of the above, please be aware of the following:

1. Node-related tooling requirements are now:

- Minimum `node` version: 18
- Minimum `npm` version: 10

2. SSL Certificates:

SSL for hosting add-ons is now managed from the following locations:

- Mac: `/Users/[user]/Library/Application Support/Adobe/CCWebAddOn/devcert`
- Windows: `C:\Users\Administrator\AppData\Local\Adobe\CCWebAddOn\devcert`

After updating `@adobe/ccweb-add-on-scripts` to `3.0.0`, developers will be asked to re-create their SSL certificate.

For a new add-on created using `npx @adobe/create-ccweb-add-on@3.0.0`, a new SSL certificate will be set up one-time.

For removing expired SSL certificate or certificate authority, developers can now run: `npx @adobe/ccweb-add-on-ssl purge`, and re-create them using `npx @adobe/ccweb-add-on-ssl setup --hostname localhost`

3. Spectrum Web Components

- The version of `@swc-react` components in the templates based on React has been updated to `1.0.3`.
- The version of `@spectrum-web-components` components in the templates based on SWC has been updated to `1.1.2`.
- The theme usage has been updated to use the `system` attribute instead of `theme`, ie:

  - SWC: `<sp-theme system="express" color="light"  scale="medium">`
  - React: `<Theme system="express" scale="medium" color="light">`

## 2025-03-21

### Added

- A native Color Picker is available to add-ons via the [`showColorPicker()`](../references/addonsdk/addonsdk-app.md#showcolorpicker) and [`hideColorPicker()`](../references/addonsdk/addonsdk-app.md#hidecolorpicker) methods of the `addOnUiSdk.app` object.
- We've updated the [Use Color](../guides/develop/how_to/use_color.md) How-to guide, now including a few examples on the Color Picker.
- A [new section](../references/ui-components/color-picker.md) has been added to the documentation, which provides a reference for the Adobe Express built-in UI components available to add-ons, like the Color Picker.
- A new version of the `@adobe/ccweb-add-on-sdk-types` package (v1.14.0) has been released for the CLI. Run `npm update` from the root of your add-on project to update to get the latest typings.

## 2025-03-07

### Added

- A new [How-to](../guides/develop/how_to.md) section replaces the old Use Cases, expanding it to include more detailed guides on specific topics, like using Text, Color, or Geometry. Each guide includes a brief description, example code snippets, and links to relevant API references.

## 2025-03-06

### Added

- An [FAQ item](../guides/faq.md#why-is-the-cli-failing-with-an-invalid-url-error-when-creating-a-new-add-on-on-windows) was added for a known issue found where the CLI is failing on Windows when running certain versions of Node.js. The [FAQ](../guides/faq.md#why-is-the-cli-failing-with-an-invalid-url-error-when-creating-a-new-add-on-on-windows) provides a workaround for this issue.

- The following new properties have been added to the AddOnSdk [`PageMetadata`](../references/addonsdk/app-document.md#pagemetadata) API:

  - [`isBlank`](../references/addonsdk/app-document.md#pagemetadata): Allows you to check if a page is blank.
  - [`templateDetails`](../references/addonsdk/app-document.md#pagemetadata): Retrieves details about the template used to create the document.

- A new [`runPrintQualityCheck`](../references/addonsdk/app-document.md#runprintqualitycheck) method has been added to the AddOnSdk [`App.Document`](../references/addonsdk/app-document.md) API, which allows you to run a print quality check on the document to ensure that it meets print quality standards.

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** The [`runPrintQualityCheck()`](../references/addonsdk/app-document.md#runprintqualitycheck) is currently **_experimental only_** and should not be used in any add-ons you will be distributing until it has been declared stable. To use this method, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../references/manifest/index.md#requirements) section of the `manifest.json`.

## 2025-03-04

### Changed

- Stabilized the following HLAPI's:
  - The [TextNode](../references/document-sandbox/document-apis/classes/TextNode.md) API's.
  - The [fromPostscriptName()](./document-sandbox/document-apis/classes/Fonts.md#fromPostscriptName) API of [Fonts](../references/document-sandbox/document-apis/classes/Fonts.md) class.
  - The [TextContentModel](./document-sandbox/document-apis/classes/TextContentModel.md) APIs like [`TextContentModel.characterStyleRanges`](./document-sandbox/document-apis/classes/TextContentModel.md#characterstyleranges). The [`experimentalApis`](../references/manifest/index.md#requirements) flag is no longer required to use these APIs.

## 2025-03-03

### Changed

- The Per Element Metadata APIs have been stabilized. You can refer to the [AddOnData](../references/document-sandbox/document-apis/classes/AddOnData.md) class for details. The [`experimentalApis`](../references/manifest/index.md#requirements) flag is no longer required to use these APIs.

- The Selection Change Notification Events APIs have been stabilized. You can refer to the [Context](../references/document-sandbox/document-apis/classes/Context.md) class, which provides two methods: [`on()`](./document-sandbox/document-apis/classes/Context.md#on) and [`off()`](./document-sandbox/document-apis/classes/Context.md#off). These methods allow you to register and un-register notifications for selection changes and selection properties changes. The [`experimentalApis`](../references/manifest/index.md#requirements) flag is no longer required to use these APIs.

## 2025-02-26

### Added

**New Feature: [Add-on Icon Auto-Resizing Support](../guides/distribute/public-dist.md#step-4-enter-listing-details)**

- Icon Size Requirement: The uploaded icon must be 144 px.
- Auto-Resizing: Once uploaded, the icon will be automatically resized to:
  - Minimized Add-on Module Icon: 36 px
  - Panel Header Icon: 64 px
  - Launchpad Icon: 144 px

**API `paragraphStyleRanges`**

Added new [`TextContentModel.paragraphStyleRanges`](./document-sandbox/document-apis/classes/TextContentModel.md#paragraphstyleranges),i.e. ParagraphStyles API as experimental, to apply styles to different paragraphs of text content.

### Changed

Stabilized [`registerIframe()`](../references/addonsdk/addonsdk-app.md#registeriframe) and [`openEditorPanel()`](../references/addonsdk/app-ui.md#openeditorpanel) APIs. The [`experimentalApis`](../references/manifest/index.md#requirements) flag is no longer required to utilize these APIs.

## 2025-02-17

### Update

- Starting February 17, 2025: Listings will not be visible in the European Union unless trader information is provided.
- Compliance: Trader information will be displayed publicly on listing detail pages to comply with EU Digital Services Act (DSA) regulations.

[Add trader details now.](https://new.express.adobe.com/add-ons?mode=submission)

### Fixed

- Fixed an issue where the `addAnimatedImage()` API was not working as expected.
- Fixed the technical requirements for GIF; the maximum resolution is 1080px.

## 2025-01-27

### Changed

Stabilized [`importPdf()`](../references/addonsdk/app-document.md#importpdf) and [`importPresentation()`](../references/addonsdk/app-document.md#importpresentation) APIs. The [`experimentalApis`](../references/manifest/index.md#requirements) flag is no longer required to utilize these APIs.

## 2025-01-17

### Added

- A new [`Viewport`](./document-sandbox/document-apis/classes/Viewport.md) class has been added to the Document APIs. [`Viewport`](./document-sandbox/document-apis/classes/Viewport.md) represents the canvas area currently visible on-screen.
- A new API [`bringIntoView`](./document-sandbox/document-apis/classes/Viewport.md#bringIntoView) have been added which adjusts the viewport to make the node's bounds visible on-screen, assuming all bounds are within the artboard bounds.

## 2025-01-13

### Added

- Adds a new section in [Listing Your Add-on guidelines](../guides/distribute/guidelines/general/listing.md) which describes how to [add trader details](../guides/distribute/guidelines/general/listing.md#trader-details) in the publisher profile.

<InlineAlert variant="warning" slots="text1, text2, text3" />

**Are you an existing developer?**

You must provide trader details by February 16, 2025, to keep your add-on visible and available in Adobe Express for users in the European Union as of February 17, 2025. This trader information will be displayed publicly on your listing detail pages when viewed from EU countries.

[Add trader details now.](https://new.express.adobe.com/add-ons?mode=submission)

## 2024-11-04

### Added

- Adds a new [Cross-origin Isolation Handling](../guides/develop/coi.md) page which describes an upcoming change to how Adobe Express enforces cross-origin isolation, and the impact it may have on current add-ons, as well as those currently in-development.
- Updates the descriptions for the [`importPdf()`](./addonsdk/app-document.md#importpdf) and [`importPresentation()`](./addonsdk/app-document.md#importpresentation) functions to clarify that when used, the associated PDF or presentation file will be imported as a new Adobe Express document.

## 2024-10-08

- Adds a brand new version of the [UX Guidelines](../guides/design/ux_guidelines/introduction.md) for Adobe Express add-ons.
- Removes the experimental warnings for [`addAnimatedImage()`](./addonsdk/app-document.md#addanimatedimage) since it is now stable.
- Adds the `author` property to [`MediaAttributes`](../references/addonsdk/app-document.md#mediaattributes) to allow it to be used with the [`addAudio()`](../references/addonsdk/app-document.md#addaudio) API.

## 2024-09-30

### New

- Added many new **Text APIs** for improved text management.
  - [`TextNode.fullContent`](./document-sandbox/document-apis/classes/TextNode.md#fullcontent) accessor: returns the [`TextContentModel`](./document-sandbox/document-apis/classes/TextContentModel.md) containing the complete text string and its styles associated to the Text Flow (Threaded Text or Overflow Text).
  - [`TextNode.nextTextNode`](./document-sandbox/document-apis/classes/TextNode.md#nexttextnode) accessor: gets the next node that overflowing text will spill into.
  - [`TextNode.layout`](./document-sandbox/document-apis/classes/TextNode.md#layout) accessor: gets and sets the [`TextType`](./document-sandbox/document-apis/enumerations/TextType.md) of the text node frame.
  - [`TextNode.visualEffects`](./document-sandbox/document-apis/classes/TextNode.md#visualeffects) accessor: list of [`VisualEffectType`](./document-sandbox/document-apis/enumerations/VisualEffectType.md) applied to the text node.
  - [`TextContentModel.characterStyleRanges`](./document-sandbox/document-apis/classes/TextContentModel.md#characterstyleranges) accessor: list of [character style](./document-sandbox/document-apis/interfaces/CharacterStyles.md) ranges in the text content, controlling the [`color`](./document-sandbox/document-apis/interfaces/CharacterStyles.md#color), [`font`](./document-sandbox/document-apis/interfaces/CharacterStyles.md) ranges in the text content, controlling the [`color`](./document-sandbox/document-apis/interfaces/CharacterStyles.md#font), [`fontSize`](./document-sandbox/document-apis/interfaces/CharacterStyles.md) ranges in the text content, controlling the [`color`](./document-sandbox/document-apis/interfaces/CharacterStyles.md#fontsize), [`letterSpacing`](./document-sandbox/document-apis/interfaces/CharacterStyles.md) ranges in the text content, controlling the [`color`](./document-sandbox/document-apis/interfaces/CharacterStyles.md#letterSpacing) and [`underline`](./document-sandbox/document-apis/interfaces/CharacterStyles.md) ranges in the text content, controlling the [`color`](./document-sandbox/document-apis/interfaces/CharacterStyles.md#underline) properties.
  - [AvailableFont](./document-sandbox/document-apis/classes/AvailableFont.md) and [UnavailableFont](./document-sandbox/document-apis/classes/UnavailableFont.md) classes.
  - Supporting interfaces, enumerations and type aliases.
- Added **Per Element Metadata APIs**: with this feature, add-ons can store private metadata to any node of the Express document. This metadata is accessible only to the add-on that has set it. See the [`AddOnData`](./document-sandbox/document-apis/classes/AddOnData.md) class and the [`addOnData`](./document-sandbox/document-apis/classes/BaseNode.md#addondata) accessor for the BaseNode class.
- Added **Selection Change Notification Events APIs**: add-on can register to be notified when selection and properties in the selection changes on the document. The [`Context`](./document-sandbox/document-apis/classes/Context.md) class will expose two [`on()`](./document-sandbox/document-apis/classes/Context.md#on) and [`off()`](./document-sandbox/document-apis/classes/Context.md#off) methods which can be used to register and un-register selection change and selection properties change notifications.
- Added a new [`GridCellNode`](./document-sandbox/document-apis/classes/GridCellNode.md) class that represents a **cell in a grid**.

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This round of new APIs is currently **_experimental only_** with the exception of `TextNode.fullContent.text`, and should not be used in any add-ons you will be distributing until it has been declared stable. To use them, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../references/manifest/index.md#requirements) section of the `manifest.json`.

### Fixed

- [`GridLayoutNode.allChildren`](../references/document-sandbox/document-apis/classes/GridLayoutNode.md#allchildren) does not include rectangle nodes.

### Deprecated

- [`TextNode.text`](../references/document-sandbox/document-apis/classes/TextNode.md#text) is now deprecated; it is still working, but will be removed in a future update. Please use [`TextNode.fullContent.text`](../references/document-sandbox/document-apis/classes/TextNode.md#fullcontent) instead.

## 2024-09-24

- Adds a new [`addAnimatedImage()`](./addonsdk/app-document.md#addanimatedimage) method which can be used to add **animated GIF** images to the document (as long as they fit within certain [technical constraints](./addonsdk/app-document.md#image-requirements)).
- Adds a new [`importPdf()`](./addonsdk/app-document.md#importpdf) method which can be used to import a PDF as a new Adobe Express document.
- Adds a new [`importPresentation()`](./addonsdk/app-document.md#importpresentation) method which can be used to import a Powerpoint as a new Adobe Express document.
- Adds notes about specific support and handling for animated GIF images when [importing](./addonsdk/app-document.md#addimage) and [dragging content](./addonsdk/addonsdk-app.md#enabledragtodocument). This includes a [new FAQ item](../guides/faq.md#are-animated-gifs-supported-when-importing-or-dragging-content-to-the-document) summarizing the associated use cases.
- Adds all of the new methods mentioned above to the [How-to](../guides/develop/how_to.md) section with example code snippets for each.

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** The [`importPdf()`](./addonsdk/app-document.md#importpdf) and [`importPresentation()`](./addonsdk/app-document.md#importpresentation) methods are currently **_experimental only_** and should not be used in any add-ons you will be distributing until it has been declared stable. To use this method, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../references/manifest/index.md#requirements) section of the `manifest.json`.

## 2024-09-10

- Added a new [`replaceMedia()`](./document-sandbox/document-apis/classes/MediaContainerNode.md#replacemedia) method to the `MediaContainerNode` class that can be used to replace existing media inline.
- Refactoring done to the [`Stroke`](./document-sandbox/document-apis/interfaces/Stroke.md) APIs.

## 2024-07-22

- Added a new [`format`](../references/addonsdk/app-ui.md#format) property to the `addOnUISdk.app.ui` object that reflects the format used to display dates, times, numbers, etc. in the user's environment. It supports a [`"formatchange"`](../references/addonsdk/app-ui.md#formatchange) event triggered when the format changes—see an example in the [Locale, Supported Locales, and Format](../guides/develop/how_to/theme_locale.md) section.
- Removed `mobile` and `app` as [`supportedDeviceClass`](../references/manifest/index.md#requirementsappssupporteddeviceclass) values in the Manifest's `requirements.apps` object.

## 2024-05-28

- Added a new _experimental_ [`openEditorPanel()`](../references/addonsdk/app-ui.md#openeditorpanel) API to programmatically open and interact with the Editor panel. This method of the `addOnUISdk.app.ui` allows navigation to specific tabs and collections, as well as performing content searches. The [Constants](../references/addonsdk/addonsdk-constants.md) page has been updated accordingly.
- Added a new [`Cross-Origin-Embedder-Policy`](../guides/faq.md#how-do-i-prevent-my-iframe-content-from-being-blocked-due-to-cross-origin-issues) FAQ.

## 2024-05-21

- The [Quickstart](../guides/getting_started/quickstart.md) and [Distribute](../guides/distribute/index.md) guides have been updated to reflect major UI/UX improvements for in-app workflows, particularly around distribution and listing management.
- The Add-ons tab is now active also in the Adobe Express home page, regardless of whether a project is open or not.
- A new section on Marketplace [rejections](/guides/distribute/rejections.md) has been added, highlighting the most common problems found during the add-on review process and how to avoid them.
- The [Manifest Reference](./manifest/index.md) has been updated with two new permission properties: `microphone` and `camera`.

## 2024-04-10

- A new [`VisualNode`](./document-sandbox/document-apis/classes/VisualNode.md) class has been added to the Document APIs, and represents any node that can be visually perceived in the content.
- New Document APIs have been added:
  - [`currentPage`](./document-sandbox/document-apis/classes/Context.md#currentpage) Context accessor: returns the active page.
  - [`visualRoot`](./document-sandbox/document-apis/classes/VisualNode.md#visualroot) accessor: the highest ancestor that still has visual presence in the document—typically, an Artboard.
  - [`cloneInPlace()`](./document-sandbox/document-apis/classes/PageNode.md#cloneinplace) method: clones a Page, all artboards within it, and all content within those artboards.
  - Support to Bounds has been added in several classes: [`boundsInParent`](./document-sandbox/document-apis/classes/Node.md#boundsinparent); `boundsLocal` (for both [GroupNode](./document-sandbox/document-apis/classes/GroupNode.md#boundslocal) and [VisualNode](./document-sandbox/document-apis/classes/VisualNode.md#boundslocal)); [`centerPointLocal`](./document-sandbox/document-apis/classes/VisualNode.md#centerpointlocal); [`topLeftLocal`](./document-sandbox/document-apis/classes/VisualNode.md#topleftlocal); [`boundsInNode()`](./document-sandbox/document-apis/classes/Node.md#boundsinnode); [`localPointInNode()`](./document-sandbox/document-apis/classes/VisualNode.md#localpointinnode);
- The CLI has been updated to release version `2.0.0`, and includes the following:

  - Periodic login and EULA consent are no longer required.
  - Two new templates for creating add-ons with built-in support to Spectrum Web Components have been added and documented: `swc-javascript` and `swc-javascript-with-document-sandbox`. Typescript templates have been renamed to `swc-typescript` and `swc-typescript-with-document-sandbox`. See [this page](/guides/getting_started/dev_tooling.md#templates) for details on all the available templates.
  - Typings have been updated to include the latest SDK changes, and other internal packages are now at version `2.0.0`.

  **NOTE:** The new version should be installed by default when you create a new add-on. If, for any reason, it doesn't, you can force it to install by clearing the `npx` cache first with `npx clear-npx-cache` or by specifying the version in the command, i.e.: `npx @adobe/create-ccweb-add-on@2.0.0 my-add-on`.

- The [Samples](../samples.md) page has been updated to document the existing add-ons in the [`express-add-on-samples`](https://github.com/AdobeDocs/express-add-on-samples) repository, including a newly added [`audio-recording-addon`](../samples.md#audio-recording-addon).
- The [Common Use Cases](/guides/develop/use_cases) section has been refactored as a sub-menu, grouping similar topics into individual pages. A new [Login and Logout flows](/guides/develop/how_to/oauth2.md#login-and-logout-flows) section has been added. Other minor fixes and improvements have been made to the documentation.

## 2024-03-19

- Support for Ps and Ai files to be added to the page via the [`addImage()`](../references/addonsdk/app-document.md#addimage) method. (Note: there were no changes to the drag-n-drop APIs).
- Adds new `MediaAttributes` parameter to the [`addImage()`](../references/addonsdk/app-document.md#addimage) method for Ps/Ai file types to pass media attributes like `title`.
- Adds new [`Mp4RenditionOptions`](../references/addonsdk/app-document.md#mp4renditionoptions) object to support `mp4` renditions.
- Adds new [`VideoResolution`](../references/addonsdk/addonsdk-constants.md) constant to set video resolution options.
- Adds [`registerIframe()`](../references/addonsdk/addonsdk-app.md#registeriframe) method and [`unregisterIframe`](../references/addonsdk/addonsdk-app.md#unregisteriframe-type-definition) type definition with example usage. **NOTE:** These APIs are currently experimental.

## 2024-03-08

- [`getPagesMetadata()`](../references/addonsdk/app-document.md#getpagesmetadata), [`startPremiumUpgradeIfFreeUser`](../references/addonsdk/addonsdk-app.md#startpremiumupgradeiffreeuser) and [`isPremiumUser`](../references/addonsdk/app-currentUser.md#ispremiumuser) have been moved to stable and no longer require the `experimentalApis` flag to be set.
- New examples have been added to the [use cases guide](../guides/develop/how_to/premium_content.md) for handling premium content.
- A new video has been added to the [grids tutorial](../guides/tutorials/grids-addon.md) to help guide developers in building the grids add-on.

## 2024-02-21

- New support for [monetization details](../guides/distribute/public-dist.md#step-8-enter-the-monetization-details) has been added to the public distribution flow and allows you to [provide details around monetization options](../guides/distribute/public-dist.md#step-8-enter-the-monetization-details) your add-on supports. A selection will now be required when you submit a new add-on to the marketplace or update an existing one. The options include _free_, _one-time payment_, _recurring subscription_, _micro-transactions_, and _other_.

  In addition, the [monetization guidelines](../guides/distribute/guidelines/monetization.md) were updated with details to help guide you in communicating your monetization strategy, and include new branding [badges](../guides/distribute/guidelines/monetization.md#branding-assets-for-monetization) you can use to visually indicate when content or features require a purchase or when they are paid and unlocked. Please ensure you review the [updated monetization guidelines](../guides/distribute/guidelines/monetization.md) carefully for specific details. **NOTE:** Adobe does not currently provide a specific monetization feature, but with this update, provides a way for developers to communicate the monetization details of their add-ons.

- The first phase of add-on analytics support has been released, and allows developers to [download insights data](../guides/distribute/public-dist.md#post-submission-details-and-insights) for their published add-ons via the [Download insights](../guides/distribute/public-dist.md#post-submission-details-and-insights) button in the in-app distribution modal.
- A new [Concepts guide](../references/document-sandbox/document-apis/concepts/index.md) was added to the [Document APIs](../references/document-sandbox/document-apis/) section to provide a deep-dive into the architecture and key elements of the Adobe Express Document Object Model (DOM).

## 2024-02-14

- A new `id` accessor has been added to the [`BaseNode`](../references/document-sandbox/document-apis/classes/BaseNode.md) class in the Document APIs and is inherited by all classes that extend it. The `id` represents a unique identifier that stays the same when the file is closed and reopened, or if the node is moved to a different part of the document.

## 2024-02-07

- A new [`createPath`](../references/document-sandbox/document-apis/classes/Editor.md#createpath) method is now available for allowing you to create a path with the Document APIs.
- Updates descriptions in various methods and classes in the [Document APIs](../references/document-sandbox/document-apis/).
- Updates to the [`createRenditions`](../references/addonsdk/app-document.md#createrenditions) API, including a new [`print`](../references/addonsdk/addonsdk-constants.md) option for `RenditionIntent` to be be used for generating a print optimized pdf, and an update to [`PdfRenditionOptions`](../references/addonsdk/app-document.md#pdfrenditionoptions) which exposes the ability to customize each PDF Page Box's (`MediaBox`, `BleedBox`, `CropBox`, `TrimBox`) dimensions using a `pageBoxes` property.
- Updates to the [Using Adobe Spectrum tutorial](https://developer.adobe.com/express/add-ons/docs/guides/tutorials/spectrum-workshop/) with additional details on [why you should use Spectrum CSS variables](../guides/tutorials/spectrum-workshop/part3.md#styling-with-spectrum-css) to style your add-ons, and [additional helpful guidelines for locating and using them](../guides/tutorials/spectrum-workshop/part3.md#layout-and-typography-styling).
- The table of contents in each Document API class/interface/constant has been removed since it was a duplicate of the right side navigation menu.

## 2024-01-31

Added a new tutorial - [Building UIs using Adobe's Spectrum Design System](https://developer.adobe.com/express/add-ons/docs/guides/tutorials/spectrum-workshop/).

## 2024-01-09

### New Experimental APIs

- [`startPremiumUpgradeIfFreeUser()`](../references/addonsdk/addonsdk-app.md#startpremiumupgradeiffreeuser) experimental API has been added to the [addOnUISdk.app](../references/addonsdk/addonsdk-app.md) object to display the in-app monetization upgrade flow and returns a value indicating whether the user upgraded to premium or not.

- [`isPremiumUser()`](../references/addonsdk/app-currentUser.md#ispremiumuser) experimental API has been added to the [addOnUISdk.app.currentUser](../references/addonsdk/app-currentUser.md) object to determine if the current user is a premium or free user.

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** The above new APIs are currently **experimental only** and should not be used in any add-ons you will be distributing until declared stable. To use these APIs, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../references/manifest/index.md#requirements) section of the `manifest.json`.

### Additional Updates

- A new [`PdfRenditionOptions`](../references/addonsdk/app-document.md#pdfrenditionoptions) object is now available to be used with the the [`createRenditions()` export API](../references/addonsdk/app-document.md#createrenditions) and allows a user to specify an optional [bleed](../references/addonsdk/app-document.md#bleed) object (for printing).
- A new [`isPrintReady`](../references/addonsdk/app-document.md#pagemetadata) property has been added to the [`PageMetadata` API](../references/addonsdk/app-document.md#pagemetadata) to indicate if the page is ready to print.
- Updated the [FAQ](../guides/faq.md#what-mime-type-is-returned-from-a-pdf-that-was-exported-with-the-createrenditions-method) regarding the mime type for exported PDF files. It will now return `application/pdf` (as opposed to `text/plain` from an earlier update).

## 2023-12-07

<InlineAlert slots="text" variant="warning"/>

**BREAKING NEWS:** The [Adobe Express Document Sandbox](../references/document-sandbox/) and all associated APIs have been deemed stable, and **no longer require the `experimentalApis` flag**. As a result, some breaking changes with these experimental APIs were introduced before deeming them stable, and they are summarized below. Please read them thoroughly and update your in-development add-ons as needed. If you run into any issues, please reach out to us on our [Adobe Express Add-on Developer’s Discord channel](http://discord.gg/nc3QDyFeb4) for help.

### Breaking changes (experimental APIs)

Some items in the following list of changes may have been mentioned in recent updates but are being listed in this summary again to serve as a reminder.

- The methods in the [Document API Editor class](../references/document-sandbox/document-apis/classes/Editor.md) to create a color fill and stroke have been renamed to [`makeColorFill`](../references/document-sandbox/document-apis/classes/Editor.md#makecolorfill) and [`makeStroke`](../references/document-sandbox/document-apis/classes/Editor.md#makestroke) respectively.
- `strokes` and `fills` have been renamed to their singular counterpart. (Express does not support multiple strokes or fills). You should use `stroke` and `fill` going forward to access them, and they will no longer be `ItemList` objects, since they represent only a single stroke or fill.

  ```js
  // Before
  rectangle.fills.append(rectFill);
  ellipse.fills.append(ellipseFill);

  // After
  rectangle.fill = rectFill;
  ellipse.fill = ellipseFill;
  ```

  - `fill` and `stroke.color` are just a [color object](../references/document-sandbox/document-apis/interfaces/Color.md) of the form `{ red, green, blue, alpha }`.
  - `stroke` is an object of the form `{ color, width, dashPattern, dashOffset }`

- Color utilities have moved to [`colorUtils`](../references/document-sandbox/document-apis/classes/ColorUtils.md) instead of `utils`.

  **Old**<br/>
  <del>

  ```js
  import { utils } from "express-document-sdk";
  const color = utils.createColor(1, 0, 0);
  ```

  </del>

  **New**<br/>

  ```js
  import { colorUtils } from "express-document-sdk";

  // any of:
  const color = colorUtils.fromRGB(1, 0, 0); // optional alpha
  const color = colorUtils.fromRGB({ red: 1 , green: 0, blue: 0 };); // optional alpha
  const color = colorUtils.fromHex("#ff0000");
  const color = { red: 1, green: 0, blue: 0, alpha: 1 }; // mandatory alpha
  ```

  - `fromHex` returns a color from a Hex string -- e.g., `colorUtils.fromHex("#FF8040")` or `colorUtils.fromHex("#FF8040FF")` (including the optional alpha);
  - `fromRGB` returns a color from a set of RGB(A) values (0-1) -- e.g., `colorUtils.fromRGB(1,0.5,0.25,1)`.
  - `toHex` converts a color object to a Hex string -- e.g., `colorUtils.toHex(aColor)`.

- `allChildren` returns an `iterator`, not an `Array`. However if you want to use array methods (ie: `Array#map`), you can use `Array.from` to convert it to an array.
- Strokes and fills will no longer _move_ if you add an existing `stroke`/`fill` to another shape (previously the original shape would lose the corresponding `stroke` or `fill`). For example:

  ```js
  // Old way
  const greenFill = editor.createColorFill(colorUtils.fromRGB(0, 0, 1));
  someRect.fills.append(greenFill);
  anotherRect.fills.append(greenFill);
  /* oops, someRect no longer has a green fill, because anotherRect is its parent */
  ```

  versus:

  ```js
  // New way
  const greenFill = editor.makeColorFill(colorUtils.fromRGB(0, 0, 1));
  someRect.fill = greenFill;
  anotherRect.fill = greenFill;
  /* both rectangles have a green fill */
  ```

- Some things that previously didn't make sense will now cause compile errors in typescript, or throw in javascript:
  - Do not assume a node's parent is movable — e.g., an artboard can't be repositioned.
  - Not all shapes support setting `opacity` or `locking` (e.g, the document root or an artboard).
- The `translateX` and `translateY` properties have been replaced by a single translation object.

  ```js
  // old
  rectangle.translateX = 100;
  rectangle.translateY = 20;

  // new
  rectangle.translation = { x: 100, y: 20 }; // both x,y properties are required
  ```

- A new [`BaseNode`](../references/document-sandbox/document-apis/classes/BaseNode.md) class has been introduced, and [`ContainerNode`](../references/document-sandbox/document-apis/interfaces/ContainerNode.md) has been moved from a class to an interface.
- The key to load APIs that use the Document APIs has changed, as well as the module names you import APIs from in the [Document Sandbox](../references/document-sandbox/). The old ones will still work, but the CLI and templates have all been updated to use the new names. Please update your add-ons to use the new ones shown below:

  **Adobe Express Document APIs SDK import**<br/>
  For access to the [Express document and content authoring APIs](../references/document-sandbox/document-apis/):

  <del>

  ```js
  // Old
  import { editor } from "express";
  ```

  </del>

  ```js
  // New
  import { editor } from "express-document-sdk";
  ```

  **Document Sandbox SDK import**<br/>
  For access to the [document sandbox runtime APIs](../references/document-sandbox/):

  <del>

  ```js
  // Old
  import AddOnScriptSdk from "AddOnScriptSdk";
  ```

  </del>

  ```js
  // New
  import addOnSandboxSdk from "add-on-sdk-document-sandbox";
  ```

- The [`manifest.json` entry point](../references/manifest/index.md#entrypoints) for the document sandbox script code reference was renamed from `script` to `documentSandbox`, as shown below:

  ```json
    "entryPoints": [
          {
              "type": "panel",
              "id": "panel1",
              "main": "index.html",
              "documentSandbox": "code.js" // used to be "script": "code.js"
          }
      ]
  ```

- The [`apiProxy()`](./addonsdk/instance-runtime.md#apiproxy) method in the [`addOnSandboxSdk.instance.runtime`](./addonsdk/addonsdk-instance.md#objects) object now accepts `"documentSandbox"` as a parameter when referring to the entry point in the manifest where your document sandbox code resides, instead of `"script"`.
- The [`RuntimeType`](../references/addonsdk/addonsdk-constants.md) constant now uses the value of `"documentSandbox"` in lieu of `"script"`.

  **IMPORTANT:** The above updates should be considered breaking changes, so any add-ons in development that relied on the experimental APIs may not work correctly until you make changes to use the new/updated ones above. The intention was to ensure these important changes were made prior to marking the APIs stable to 1) make them more intuitive for developers, 2) significantly improve the process of working with colors, strokes and fills, and 3) prevent certain operations from corrupting the document.

- The CLI has been updated to release version `1.1.1`, and includes the following:

  - The document sandbox templates have been updated to reflect all of the latest changes to the [Document Sandbox APIs](../references/document-sandbox/), and the `experimentalApis` flag has been removed. Please review the updated [references](../references/document-sandbox/) and changelog entries thoroughly for details on all of the recent changes. You may also want to refer to the [document sandbox code samples](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples) for additional help on how to use them.
  - Typings support has been added to the `javascript` templates to enable intellisense features.
  - Manifest property additions.
  - General improvements and bug fixes.

  **NOTE:** The new version should be installed by default when you create a new add-on. If, for any reason, it doesn't, you can force it to install by clearing the npx cache first with `npx clear-npx-cache` or by specifying the version in the command, i.e.: `npx @adobe/create-ccweb-add-on@1.1.1 my-add-on`. You can update any existing add-ons to use this new version by updating the version of the `ccweb-add-on-scripts` in the `package.json` to `1.1.1`.

- All [code samples](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples) and the [Document API tutorial](../guides/tutorials/grids-addon.md) have also been updated to reflect all of the latest changes to the [Adobe Express Document Sandbox APIs](../references/document-sandbox/document-apis/) listed here.
- Removed all experimental APIs notes/warnings around the **Document Sandbox** since they **are now stable**.

<InlineAlert slots="text" variant="warning"/>

**Known Issue:** Please note, there is an edge case where **removing a page with your add-on** could potentially cause a problem where the UI needs to be reloaded. This will be resolved in the very near future, but please take caution and be aware that it would be best to avoid page removal in the short-term until it's resolved.

### Additional Updates

- A new `getPagesMetadata()` method is now available in the [Add-on UI SDK `document`](../references/addonsdk/app-document.md#getpagesmetadata) object and includes an example code snippet. **NOTE:** This method is still considered **experimental only** and should not be used in any add-ons you will be distributing until it has been declared stable. To use this method, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../references/manifest/index.md#requirements) section of the `manifest.json`.
- The [`createRenditions()` export API](../references/addonsdk/app-document.md#createrenditions) was updated with the following changes:
  - You can now choose to generate renditions of specific pages via a new [`Range.specificPages`](../references/addonsdk/addonsdk-constants.md) constant value.
  - The returned type now also includes page metadata (see [`PageMetadata`](../references/addonsdk/app-document.md#pagemetadata)) including useful information such as the id, page size, pixels per inch, and whether the page has premium or temporal (timeline) content or not, (in addition to the existing blob and title). An example is provided in the reference as well as in [the use cases](../guides/develop/how_to/page_metadata.md).
- A new [document metadata use case example](../guides/develop/how_to/document_metadata.md) has been added to show how to retrieve the [document id](./addonsdk/app-document.md#id) and [title (ie: name)](./addonsdk/app-document.md#title), including how to listen for the [associated events](../references/addonsdk/addonsdk-app.md#events).
- New tables have been added to the [Communication API reference](../references/document-sandbox/communication/index.md) denoting the [supported](../references/document-sandbox/communication/index.md#supported-data-types) and [unsupported data types](../references/document-sandbox/communication/index.md#unsupported-data-types) that can be used across the [Communication API](../references/document-sandbox/communication/index.md) layer.

## 2023-12-04

### Updates

- The [Document API's](./document-sandbox/document-apis/) were updated to add a new [`ColorUtils`](./document-sandbox/document-apis/classes/ColorUtils.md) class, which replaces the previous `utils` module that was used as a color helper with a more enhanced utlility. If you've used the old `utils` module in your add-ons, it will require you to update them to use the new named import of `colorUtils` instead of `utils`. Color creation should now be done using the new [`colorUtils` module](./document-sandbox/document-apis/classes/ColorUtils.md). An example of the old way and new way to create a color are shown below for reference:

  ```js
  // Before
  import { utils } from "express-document-sdk";
  const color = utils.createColor(1, 0, 0);

  // After
  import { colorUtils } from "express-document-sdk";

  // any of:
  const color = colorUtils.fromRGB(1, 0, 0); // optional alpha
  const color = colorUtils.fromRGB({ red: 1, green: 0, blue: 0 }); // optional alpha
  const color = colorUtils.fromHex("#ff0000");
  const color = { red: 1, green: 0, blue: 0, alpha: 1 }; // mandatory alpha
  ```

  The [code samples](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples) have also been updated, so please also refer to those for further details on how to use it. Please note, the [example code snippets](../references/document-sandbox/document-apis/index.md#example-code-snippet) and samples using `fills` or `strokes` off a node class were also updated to use a singular `Fill` or `Stroke` object instead of as an `ItemList` object.

  ```js
  // Before
  rectangle.fills.append(rectFill);
  ellipse.fills.append(ellipseFill);

  // After
  rectangle.fill = rectFill;
  ellipse.fill = ellipseFill;
  ```

- A new release has landed for the [**In-App Developer Submission experience**](../guides/distribute/) in Express. Some highlights from the release:

  **Create Add-on flow:** You can now create [an add-on "container"](../guides/distribute/public-dist.md#step-2-add-on-listing-settings) as your first step in building add-ons within the existing in-app distribution workflow. Creating the container gets you access to a few important settings and data (for instance your unique subdomain, see below) before you continue the development process in the CLI. All existing add-ons will automatically receive a parent container with the associated additional features today.

  **Unique Subdomain retrieval:** As part of your add-on container, you will now be able to easily retrieve a unique subdomain for your add-on. Simply choose one of your add-ons in the distribution workflow and navigate to the new "Settings" tab and copy the Add-on URL. This URL is handy for addressing issues with CORS by adding the URL as an allowed origin. See [our CORS guide](../guides/develop/context.md#cors) for more details.

  **Delete Add-ons:** The "container" concept allowed us to offer better management and cleanup of your add-ons. You will now find the option to delete an add-on container entirely from the new "Settings" tab of a given add-on.

  **NOTE:** You can only delete add-ons that have not been published publicly or submitted to our Review team. Please contact us if you need to un-publish an add-on.

  **Supported Languages:** The [version details step](../guides/distribute/public-dist.md#step-4-enter-listing-details) for publishing add-ons publicly now includes fields to indicate which languages are supported by your add-ons (beyond the required English). You can choose from any of the languages Express supports, and your designation will be shown to users when they browse your listing details. See [our sample for detecting a user's locale to localize your add-on](../guides/develop/how_to/theme_locale.md).

- Updated list of templates and details to include the [Document Sandbox template options](../guides/getting_started/dev_tooling.md#templates), and how to still scaffold from one when the [`--template` parameter is not explicitly supplied](../guides/getting_started/dev_tooling.md#no-template-parameter).
- New FAQ item regarding the mime type for exported PDF files. This is due to an unexpected change made in Adobe Express core to the mime type returned when you generate a PDF using the export [`createRenditions`](../references/addonsdk/app-document.md#createrenditions) method. In the past it would return `application/pdf`, but currently it returns `text/plain`. This is something to be aware of if you are inspecting the mime type in the response and failing if it's anything other than `application/pdf`.
- Removed NPS survey.

## 2023-11-30

### Updates

- Adds support to the [Add-on UI SDK](./addonsdk/index.md) for retrieving the [document id](./addonsdk/app-document.md#id) and [title](./addonsdk/app-document.md#title), as well as the ability for the add-on to be notified of the [associated events](../references/addonsdk/addonsdk-app.md#events).
- Updates the names of the SDK imports for the [Document Sandbox](../references/document-sandbox/communication/index.md) and the [Document API's SDK](./document-sandbox/document-apis/):

  **Document Sandbox SDK import**<br/>

  from:

  `import AddOnScriptSdk from "AddOnScriptSdk";`

  to:

  `import addOnSandboxSdk from "add-on-sdk-document-sandbox";`

  which also requires the following line to change in the example code to use the new reference:

  `const { runtime } = addOnSandboxSdk.instance; // runtime object provides direct access to the comm methods`

  **Express Document SDK Import (for accessing the Document APIs**<br/>

  from:

  `import { editor } from "express";`

  to:

  `import { editor } from "express-document-sdk";`

  **NOTE:** This includes the named imports for `utils` and `constants` modules as well if needed (ie: `import { editor, utils, constants } from "express-document-sdk"`).

- Updates the [`manifest.json` entry for the document sandbox script code reference](../references/manifest/index.md#entrypoints) from `script` to `documentSandbox`, as shown below:

  ```json
    "entryPoints": [
          {
              "type": "panel",
              "id": "panel1",
              "main": "index.html",
              "documentSandbox": "code.js"
          }
      ]
  ```

- [`apiProxy()`](./addonsdk/instance-runtime.md#apiproxy) now accepts `"documentSandbox"` as a parameter when referring to the entry point in the manifest where your document sandbox code resides, instead of `"script"`.
- The [`RuntimeType`](../references/addonsdk/addonsdk-constants.md) constant can now have a value of `"documentSandbox"` in lieu of `"script"`.

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** The old import names will continue to be supported for a period of time to allow developers to migrate to the new import names, but we encourage you to update as soon as possible to avoid any future issues.

## 2023-11-28

### Updates

- The [Web API's in the Document Sandbox Reference](./document-sandbox/web/index.md) were updated to remove the timer methods which are no longer supported (ie: `setTimeout()`, `clearTimeout` and `setInterval()`, `clearInterval`).
- The [Document API References](./document-sandbox/document-apis/) were updated with the following additions and changes:

  **New Classes/Interfaces**<br/>

  - New [RestrictedItemList class](./document-sandbox/document-apis/classes/RestrictedItemList.md)
  - New [UnknownNode class](./document-sandbox/document-apis/classes/UnknownNode.md)
  - New [SolidColorShapeNode class](./document-sandbox/document-apis/classes/SolidColorShapeNode.md)
  - New [Point interface](./document-sandbox/document-apis/interfaces/Point.md)
  - New `queueAsyncEdit` method added to the [Editor](./document-sandbox/document-apis/classes/Editor.md) class.
  - Renames the [Constants](../references/document-sandbox/document-apis/enumerations/) to remove the `Value` suffix.

  **Updates to Node Classes**<br/>

The accessors and methods below were removed or replaced with new names in the [`Node` class](./document-sandbox/document-apis/classes/Node.md) and classes that extend it. Please refer to the [Document API References](./document-sandbox/document-apis/) specifically to learn more about each.

- Removes `absoluteRotation` accessor
- Removes `absoluteTransform` accessor
- Removes `relativeRotation` accessor
- Removes `relativeTransform` accessor
- Removes `translateX` accessor
- Removes `translateY` accessor
- Adds `rotation` accessor
- Adds `rotationInScreen` accessor
- Adds `transformMatrix` accessor
- Adds `translation` accessor
- Adds `setPositionInParent` method
- Adds `setRotationInParent` method

## 2023-11-27

Updated [Document API references](./document-sandbox/document-apis/) to include:

- [ComplexShapeNode class](./document-sandbox/document-apis/classes/ComplexShapeNode.md)
- [GridLayoutNode class](./document-sandbox/document-apis/classes/GridLayoutNode.md)
- [IStrokableNode interface](./document-sandbox/document-apis/interfaces/IStrokableNode.md)
- [FillRule constant](./document-sandbox/document-apis/enumerations/FillRule.md)

## 2023-11-6

- Added a [new tutorial section](../guides/tutorials/) to the Getting Started guides, including a new ["Building your first add-on with the Document API" tutorial](../guides/tutorials/grids-addon.md) by Davide Barranca.
- Updated the naming conventions from Script Runtime to Document Sandbox and Editor APIs to Adobe Express Document APIs. The Document Sandbox now includes the Communication APIs, Web APIs and the Document APIs.
- Updated sample code snippets to use the `addOnUISdk` import name (vs `AddOnSDK`) similar to what's generated in the templates for consistency.

## 2023-10-26

### Updates

New questions and answers added to the FAQ regarding Adobe's use of add-on data, where to file feature requests and more.

## 2023-10-10

### Updates

Updates to the [OAuth APIs](./addonsdk/app-oauth.md) to allow for a new optional `windowSize` parameter to be specified in the [`AuthorizationRequest`](./addonsdk/app-oauth.md#authorizationrequest) object and the [`AuthorizeWithOwnRedirectRequest`](./addonsdk/app-oauth.md#authorizewithownredirectrequest) to set the desired size of the authorization window.

## 2023-10-09

### Updates

Published new [Guidelines and requirements section](../guides/distribute/guidelines/); including [General guidelines](../guides/distribute/guidelines/general/), [Developer brand guidelines](../guides/distribute/guidelines/), [Monetization guidelines](../guides/distribute/guidelines/monetization.md) and [Generative AI guidelines](../guides/distribute/guidelines/genai/).

## 2023-10-03

### Updates

New versions of the CLI packages:

```json
  "@adobe-ccwebext/ccweb-add-on-manifest": "1.5.0"
  "@adobe-ccwebext/ccweb-add-on-core": "1.5.0"
  "@adobe-ccwebext/ccweb-add-on-ssl": "1.5.0"
  "@adobe-ccwebext/ccweb-add-on-analytics": "1.5.0"
  "@adobe-ccwebext/ccweb-add-on-developer-terms": "1.5.0"
  "@adobe-ccwebext/create-ccweb-add-on": "1.5.0"
  "@adobe-ccwebext/ccweb-add-on-scaffolder": "1.5.0"
  "@adobe-ccwebext/ccweb-add-on-scripts": "1.5.0"
  "@adobe-ccwebext/ccweb-add-on-sdk-types": "0.3.0"
```

which include:

- Updated templates for both iframe and document sandbox add-ons:

  - All new add-ons created (other than those based on javascript) use `spectrum-web-components` with the Express theme pre-set.
  - React-based templates include [`swc-react`](https://opensource.adobe.com/spectrum-web-components/using-swc-react/) setup.
  - The `javascript-with-editor-apis` template has been removed from the initial template selection in this version but replaced with the option from the CLI to [include the document sandbox](https://developer.adobe.com/express/add-ons/docs/references/document-sandbox/#cli-generated-script-runtime-add-on) when creating a new add-on.

- New type support for typescript based add-ons.
- Ability to recreate your SSL certificates.

#### Documentation updates

- Updated [document sandbox Reference docs](https://developer.adobe.com/express/add-ons/docs/references/document-sandbox/#cli-generated-script-runtime-add-on) to reflect the new CLI prompt to include document sandbox (vs the specific template).
- Updated [Getting Started guides](../guides/getting_started/) documentation and screenshots to reflect the **new Add-on Launchpad panel update** to the new **two-tab view** for "Discover" and "Your Add-ons".

## 2023-09-26

### Removed

- Removed the experimental APIs notes/warnings around the **Audio APIs and User APIs** since they **are now stable**.
- Removed references to the Dropbox sample since the [import-images-from-oauth](https://developer.adobe.com/express/add-ons/docs/samples/#import-images-using-oauth) contains the same functionality.

### Updated

- Updated the Express add-ons [introduction video](https://developer.adobe.com/express/add-ons/docs/guides/) with a newly created version.

## 2023-09-25

### Updates

The [Editor API references](https://developer.adobe.com/express-add-on-apis/docs/api/classes/Editor/) have been updated with additional descriptions and details as well as some new and modified APIs:

- Artboard now has a single fill only. **Note:** it's possible that all node types will move to this model in the near future.
- The `name` property is now only available on `PageNode`, not all node types.
- New `Node.locked` & `Context.selectionIncludingNonEditable` properties were added for the locking feature that recently shipped in Express.

<InlineAlert slots="text" variant="info"/>

If you're using the experimental Document Sandbox APIs in any add-ons currently, we encourage you to check the specific methods and objects you're using in these [updated references](https://developer.adobe.com/express-add-on-apis/docs/api/classes/Editor/) to discover anything new or changed.

## 2023-09-19

### Added

- New [iframe Sandbox Context guide](../guides/develop/context.md) with details on the new `subdomain` support and CORS handling.
- How-to videos embedded in various guides to help visually show how to use the information in those sections.

### Updates

- **New Types Package Versions Released** <br/>

  - A new version `0.1.6` of the `@adobe-ccwebext/ccweb-add-on-sdk-types` package with the latest typings for the [`AddOnSDK` (iframe)](https://developer.adobe.com/express/add-ons/docs/references/addonsdk/), including new experimental APIs, as well as general improvements and bug fixes.
  - A new version `0.2.0` of the `@adobe-ccwebext/ccweb-add-on-sdk-types` package with the latest typings for the **document sandbox/Editor APIs**.

  **IMPORTANT**:
  Developers who are **NOT** using the [document sandbox/Editor APIs](https://developer.adobe.com/express/add-ons/docs/references/document-sandbox/) should update to their types package to `0.1.6` at minimum by changing the version of it to `@adobe-ccwebext/ccweb-add-on-sdk-types@0.1.6` in the `package.json`.

  The new types `0.2.0` types package will be used automatically for any new add-ons created. If you would like to update an existing add-on to the `0.2.0` version, you will need to update the `ccweb-add-on-sdk-typings.d.ts` file in your add-on with the content [here](https://github.com/adobe-ccwebext/ccweb-add-on-cli/blob/main/packages/wxp-sdk-typings/ccweb-add-on-sdk-typings.d.ts).

- [Performance guide](../guides/develop/performance.md) updates to include [**Task Manager**](https://developer.adobe.com/express/add-ons/docs/guides/develop/performance.md#task-manager) and [**Memory Consumption**](https://developer.adobe.com/express/add-ons/docs/guides/develop/performance.md#memory-consumption-monitoring) details for add-ons.
- [FAQ update](../guides/faq.md) for [`SharedArrayBuffer`](https://developer.adobe.com/express/add-ons/docs/guides/faq/#is-sharedarraybuffer-supported).

## 2023-09-12

### Updates

- Added supported file types for import and export to the [FAQ](../guides/faq.md).

## 2023-09-07

### Updates

<del>

- The <a href="../references/document-sandbox/communication/index.md">Communication API</a> in the <a href="../references/document-sandbox/">document sandbox reference section</a> was updated to change the example code importing the SDK to a default import rather than a named import as it was previously:

  from:

  `import { AddOnSdkApi } from "AddOnSdkApi";`

  to:

  `import AddOnScriptSdk from "AddOnScriptSdk";`

  Note that you can now name the imported module whatever you'd like, but for simplicity in the examples, the name is kept the same. **Since these APIs are currently experimental, this change will not impact any in-production add-ons, _however_, it will require you to update any existing usage of these APIs in progress**.

</del>

- A **new 1.4.2 version of the CLI** was also released with an updated [`javascript-with-editor-apis` template](../references/document-sandbox/index.md) reflecting the default SDK import noted in the first bullet above. The new CLI version will install automatically when you create a new add-on, or you can update existing add-ons by changing the version of the `ccweb-add-on-scripts` in the `package.json` to `1.4.2`.
- Updated the [FAQ](../guides/faq.md) with details on Experimental APIs and suppported file types for exported content.

## 2023-09-05

### Added

Added new **Audio API** documentation. You can now import audio to the current Adobe Express document in two different methods:

1. Using the new [`addAudio()`](https://developer.adobe.com/express/add-ons/docs/references/addonsdk/app-document/#addaudio) method, which requires a [`MediaAttributes`](https://developer.adobe.com/express/add-ons/docs/references/addonsdk/app-document/#mediaattributes) object containing the `title` of the audio content.
2. Using [drag and drop](https://developer.adobe.com/express/add-ons/docs/references/addonsdk/addonsdk-app/#enabledragtodocument), and supplying the [`MediaAttributes`](https://developer.adobe.com/express/add-ons/docs/references/addonsdk/addonsdk-app/#mediaattributes) object in the [`DragCompletionData`](https://developer.adobe.com/express/add-ons/docs/references/addonsdk/addonsdk-app/#dragcompletiondata).

Please note, in both cases, the `MediaAttributes` object is required for audio content, but optional for video and image content. A new code sample will be supplied in the near future, but in the meantime, please refer to the example usage snippets provided in the [SDK Reference](https://developer.adobe.com/express/add-ons/docs/references/addonsdk/app-document/#addaudio) and [Implementing Common Use Cases Guide](https://developer.adobe.com/express/add-ons/docs/guides/develop/).

<!-- <InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** The new Audio API's are currently ***experimental only*** and should not be used in any add-ons you will be distributing until they have been deemed stable. To try out these new APIs, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../manifest/index.md#requirements) section of the `manifest.json`. -->

## 2023-08-31

### Added

Added new code sample to demonstrate how to use SWC-React and set theme properties in add-ons called **swc-react-theme-sampler** to the [Code Samples](https://developer.adobe.com/express/add-ons/docs/samples/#swc-react-theme-sampler).

### Updated

- Updated the [User Interface Guide](../guides/index.md) to add more notes around the recommended use of `swc-react` over React Spectrum and to point to the new sample mentioned above.

### Fixed

- Fixed bug in the [locale](./addonsdk/app-ui.md) example.

## 2023-08-29

- Added [`currentUser` API](../guides/develop/how_to/user_info.md) details and usage example to the [SDK References](https://developer.adobe.com/express/add-ons/docs/references/addonsdk/) and [Implementing Common Use Cases Guide](../guides/develop/how_to.md).
- Added a new [licensed-addon code sample](https://developer.adobe.com/express/add-ons/docs/samples.md#licensed-addon) to illustrate how to implement monetization by leveraging the current userid.
- Added [`devFlags` API](https://developer.adobe.com/express/add-ons/docs/references/addonsdk/app-devFlags) details, which can be used to simulate certain behavior during development.

## 2023-08-17

### Bugs and Fixes

- There's currently a bug where `addArtboard` could crash the application or corrupt the document if there's no `fill` specified on the artboard. _Please ensure you always add a fill in the same frame as the artboard creation until this issue is resolved_. Also note, when this bug is fixed, the `ArtboardNode` will accept a single `fill` object, rather than an `ItemList` of `fill`(s).

- Currently, in the `addPage` API, a new page is created, but the selected context is not changed to the newly added `artboard`. As a result, from a UI perspective, the user remains on the previous page. A change will be implemented this week which will change the default context to the `artboard` child of the newly added page. This results in actual navigation to the newly added page, and all new content which is added using the Editor APIs will be added to this page.

  **IMPORTANT:** We recommend that you **_only test the use of these experimental Editor APIs against non-essential documents_**, due to the potential for loss or corruption.

### Updates

- Premium Content handling details have been added to the [Implementing Common Use Cases Guide](../guides/develop/how_to/premium_content.md). Note the warning for ensuring that you include the specified `permissions` in the [`manifest.json`](../references/manifest/index.md#entrypointspermissionssandbox) to `allow-popups` and `allow-popups-to-escape-sandbox` to ensure the pricing page can be loaded when needed (and note the addition of the `renditionPreview` flag in the [`requirements`](../references/manifest/index.md#requirements) of the manifest when you want to allow premium content to be previewed).

## 2023-08-09

### Added

- Added new [references section](../references/document-sandbox/) for the document sandbox APIs.

### Important notes on document sandbox APIs (aka Document Sandbox)

- These APIs are experimental!
  - Do not test your add-ons on documents that you care about as these APIs are not currently considered stable.
  - Be sure to only use documented APIs when writing your add-ons. Use of undocumented APIs (which may be prefixed with an underscore, but not always) is not supported and may cause your add-on to fail or lead to document corruption. Visibility of a method or property is visible via `console.log` is not an indication of whether that field is supported or documented.
- Debugging & Console messages
  - You may see "Empty transaction not added to pendingTransaction" while running code in the document sandbox. You can ignore this for now.
  - You may see "Detected a possible stutter. Excessive ECS Frame duration of ## ms" in the console. You can ignore this for now.
  - If your script code has a syntax error, the console will log an unhelpful error message (similar to `Uncaught (in promise) at adobe-internal.js:49`). Your add-on panel UI will be visible and continue to be interactive, but it won't be able to communicate with the document sandbox, resulting in what feels like non-responsive UI (e.g., clicking doesn't trigger the expected action). You'll want to configure your editor to highlight any syntax editors so that you can be sure your code is at least syntactically correct before you save.
- Intermittent issues
  - Auto reload of the add-on when a change is detected sometimes fails to work properly. This can result in changes to the UI HTML not being reflected, but can also cause the connection between the panel UI and the document sandbox to not be properly initialized (your UI may appear to be unresponsive as a result). If you encounter this situation, manually reloading the add-on from the developer panel will usually resolve the issue. We're working on a fix.
  - It's occasionally possible to run into a race condition where the communications bridge between the two contexts (panel vs document sandbox) is not set up in time. If you interact with your panel UI immediately after it's reloaded, the click may appear do nothing instead of invoking your script code. We're working on a fix for this.
- Common pitfalls
  - If you split your work on a document over multiple frames, be sure to protect against reentrancy, otherwise you may end up corrupting the user's undo stack. You should disable elements on the panel UI that could allow the user to execute your code before it is complete and then re-enable those elements when the code is done. The issue will be fixed in a future release.
  - When setting up communication between your panel UI code and your script sandbox code, calling `apiProxy()` with the wrong argument will do nothing without providing any error feedback. If communication is not working, carefully double-check your UI code is requesting the `"script"` API proxy and your script sandbox code is requesting the `"panel"` API proxy.
- Unexpected behavior

  - If the user has a selection and your add-on creates new content, the selection is cleared. This will be addressed before release. An API will be added in the future that will allow you to change the selection to content your add-on creates.
  - When you add text content to a document, font substitution is not working correctly. This means that if you use Asian-language characters, the user may see square boxes instead. If the user were to type the content manually, however, they would see the correct rendering. This issue will be fixed before release.
  - Setting a blend mode on a media container node (e.g., after calling `editor.createImageContainer`) will be visually reflected, but doesn't currently update the "Blend mode" field in the property panel.
  - Setting rotation on an empty group is ignored. Always add content (children) to a group first, and then set its rotation.
  - When removing elements from a parent element, the element may continue to show in the Adobe Express layer stack. This will be addressed in the future. This can also occur if you call `clear()` to remove all children from an element as well as when using `removeFromParent()`.
  - Shape elements added to the document by users (via the Media tab) do not support fill or stroke properties at this time. Furthermore, you should generally avoid making changes to these shapes (they'll appear as group nodes), as this could corrupt the document. We'll add protections around this in an upcoming release.
  - While the API supports adding multiple strokes to elements, Express currently only supports editing the _first_ stroke added. If you want to change the stroke of an element, _remove_ the existing strokes and then add the new stroke so that the element continues to have a single stroke. For example:

    ```js
    element.strokes.clear();
    element.strokes.append(newStroke);
    ```

- Likely API changes
  - Creating colors is currently done via `utils.createColor()`. We're likely to change how you assign colors to objects, so bear this in mind as you use the experimental APIs. Note that this means you cannot just pass a plain JS object of the form `{red, green, blue}` to the Editor APIs — it must be a color created using `utils.createColor`.
  - Editor API constants may be renamed or may change how they are accessed.
  - Fills and strokes can only be assigned to a single parent element. If you try to append a fill from one element to another element, the fill will be _moved_ and not cloned (just like moving a scenenode object from one parent to another). This behavior may change in the future.
  - There is no support for `fetch` in the document sandbox environment. You can work around this by exposing a method from your panel that your script code can call that does the work of fetching remote content. In the future we may abstract this for you automatically.
  - The `strokes` API is likely to be modified so that it only supports a single stroke.
- Typings & Typescript
  - Typings and samples showing how to use Typescript will be available in a future release.

## 2023-08-01

### Added

- Added new properties to the manifest reference for `renditionPreview` in the [`requirements`](../references/manifest/index.md#requirements) section, and the `script` property to the [`entryPoints`](../references/manifest/index.md#entrypoints) section to support the new experimental [document sandbox APIs](../references/document-sandbox/).
- Added [`DisableDragToDocument`](./addonsdk/addonsdk-app.md#disabledragtodocument-type-definition) and [`dropCancelReason`](../references/addonsdk/addonsdk-app.md#dragendeventdata) support to the [`addonsdk.app`](./addonsdk/addonsdk-app.md) reference.

## 2023-07-11

### Added

- [UX Guidelines](../guides/design/index.md) are now available!
- A new [`requestedSize`](../references/addonsdk/app-document.md#jpgrenditionoptions) parameter can now be supplied as part of the JPG and PNG rendition options passed in when exporting content with the `createRenditions` method.
- A new [`clipboard` permission](../references/manifest/index.md#entrypointspermissions) can now be set with the `clipboard-write` value in the manifest to allow an add-on to write data to the clipboard.
- Information on [using fonts](../guides/design/ux_guidelines/visual_elements.md#typography).
- CORS / COEP header handling added to the [CORS guide](../guides/develop/context.md#cors--coep-handling)

## 2023-06-08

### Added

- Initial release for the beta version of Adobe Express.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: Communication APIs
description: An introduction to the Communication APIs available in the document sandbox.
contributors:
  - https://github.com/hollyschinsky  
hideBreadcrumbNav: true
---

# Communication APIs

The communication APIs allow you to communicate between the document model sandbox (referred to as simply "document sandbox" throughout the rest of this guide), and the iframe where your add-on is running specifically, via the add-on SDK methods available for the document sandbox.

## Overview

The document sandbox and iframe runtime are two different runtime execution environments which are present on different threads in the browser. The communication APIs are based on the [Comlink library](https://github.com/GoogleChromeLabs/comlink) and provide a mechanism to allow the JavaScript code executing in each to interact. Developers can call the apis exposed in one environment (ie: document sandbox) from another environment (ie: iframe where their add-on is running) bidirectionally.

## Accessing the APIs

A default exported module from `addOnSandboxSdk` is provided to enable the communication between the iframe and the document sandbox via its' `instance.runtime` object. You can simply import the module into your script file code for use, and create a reference to the `runtime` object. For instance:

```js
import addOnSandboxSdk from "add-on-sdk-document-sandbox"; // a default import

const { runtime } = addOnSandboxSdk.instance; // runtime object provides direct access to the communication APIs
```

## Examples

The `runtime` object can then be used to access the communication methods which allow you to communicate between the two execution environments: `exposeApi()` and `apiProxy()`. The examples below show the methods in use from both the `index.html` where the iframe is running with your add-on code, and the document sandbox environment running the contents of `code.js`.

### Expose APIs from the script

This example shows how to expose APIs from the document sandbox SDK (via `code.js`) for use by the UI (via `index.html`).

#### `code.js`

```js
import addOnSandboxSdk from "add-on-sdk-document-sandbox"; 

const { runtime } = addOnSandboxSdk.instance; 

const sandboxApi = {
    performWorkOnDocument: function (data, someFlag) {
        // call the Document APIs
    },
    getDataFromDocument: function () {
        // get some data from document
    },
};
// expose these apis to be directly consumed in the UI (ie: index.html file).
runtime.exposeApi(sandboxApi);
```

#### index.html

```js
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
    const { runtime } = addOnUISdk.instance;

    // Wait for the promise to resolve to get a proxy to call APIs defined in the document sandbox
    const sandboxProxy = await runtime.apiProxy("documentSandbox");

    await sandboxProxy.performWorkOnDocument(
        {
            pageNumber: 1,
            op: "change_background_color",
            data: {
                toColor: "blue",
            },
        }, 
        true
    );

    console.log(await sandboxProxy.getDataFromDocument());
});
```

### Expose APIs from the UI

This example shows how to expose APIs from the UI (via `index.html`) for use in the document sandbox (via `code.js`).

#### `index.html`

```js
addOnUISdk.ready.then(async () => {
    console.log("addOnUISdk is ready for use.");

    const { runtime } = addOnUISdk.instance;
    const uiApi = {
        performWorkOnUI: function (data, someFlag) {
            // Do some ui operation
        },
        getDataFromUI: async function() {
            return new Promise(resolve => {
                // Example of returning a user choice from hypothetical UI
                resolve("button_color_blue");
            });
        }
    };
    // Expose the UI Apis to be used in the script code (ie: code.js)
    runtime.exposeApi(uiApi);
});
```

#### `code.js`

```js
import addOnSandboxSdk from "add-on-sdk-document-sandbox"; // default import

const { runtime } = addOnSandboxSdk.instance;

async function callUIApis() {
    // Get a proxy to the APIs defined in the UI
    const uiApis = await runtime.apiProxy("panel");
    await uiApis.performWorkOnUI(
        {
            buttonTextFont: 20,
            buttonColor: "Green"
        },
        true
    );
    
    const result = await uiApis.getDataFromUI();
    console.log("Data from UI: " + result);
}
```

<InlineAlert slots="text" variant="info"/>

**DEBUGGING:** Since the script code runs in a separate context from your add-on UI, the only support for debugging is via the `console.*` methods.

## Data Types

Data type validation is performed for both the arguments and the return types that are exchanged across the document sandbox runtimes (aka: communication API layer). A whitelist of supported data types is maintained and detailed below. All other data types will be rejected.

### Supported data types

<br/>
<table class="spectrum-Table spectrum-Table--sizeM" css="
    background-color:lavender;
    tbody {
      background-color:white;
    }">
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-headCell"><p><strong>Type</strong></p></td>
    <td class="spectrum-Table-headCell"><p><strong>Examples</strong></p></td>
</tr>
<tbody class="spectrum-Table-body">
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>Primitive types:</strong> <br/> &nbsp;&nbsp;- string <br/>  &nbsp;&nbsp;- boolean <br/> &nbsp;&nbsp;- number <br/> &nbsp;&nbsp;- Undefined<br/></p></td>
    <td class="spectrum-Table-cell"><p><pre><br/>"hello"<br/>true<br/>1<br/>undefined</pre></p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>Simple plain objects</strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>&#123; data: "world" &#125;, &#123; value : true &#125;</pre></p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>Arrays of primitive and plain objects</strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>[1,2],["hello", true, &#123; data: null &#125;]</pre></p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>ArrayBuffer</strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>new ArrayBuffer(1024)</pre></p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>Blob</strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>new Blob()</pre></p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>Error</strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>new Error()</pre></p></td>
</tr>
</tbody>
</table>

Some data types are not supported and may result unintended behavior. To avoid this, the type of argument/return type in the communication layer is checked and an error is thrown if not supported.

### Unsupported data types

<br/>
<table class="spectrum-Table spectrum-Table--sizeM" css="
    background-color:lavender;
    tbody {
      background-color:white;
    }">
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-headCell"><p><strong>Type</strong></p></td>
    <td class="spectrum-Table-headCell"><p><strong>Examples</strong></p></td>
</tr>
<tbody class="spectrum-Table-body">
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>Map</strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>new Map()</pre></p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>Set</strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>new Set()</pre></p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>DataView() </strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>new DataView(new ArrayBuffer(8))</pre></p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>Boolean</strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>new Boolean()</pre></p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>String</strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>new String(“hello”)</pre></p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>RegExp</strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>new RegExp("pattern")</pre></p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>Symbol</strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>Symbol('symbol')</pre></p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>Date</strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>new Date()</pre></p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>UserDefinedClass</strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>new UserDefinedClass() </pre></p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>Function</strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>() => &#123;&#125; </pre></p></td>
</tr>
<tr class="spectrum-Table-row">
    <td class="spectrum-Table-cell"><p><strong>Circular objects</strong> <br/></p></td>
    <td class="spectrum-Table-cell"><p><pre>const obj = &#123;&#125; obj.key = obj;</pre></p></td>
</tr>
</tbody>
</table>
[@express-document-sdk](../overview.md) / AddOnData

# Class: AddOnData

AddOnData class provides APIs to read, write, remove private metadata to a Node.
This metadata is accessible only to the add-on that has set it.

## Accessors

### remainingQuota

• `get` **remainingQuota**(): `Readonly`<`object`\>

#### Returns

`Readonly`<`object`\>

an object with the remaining quota for private metadata on the node for this add-on.
The object contains the following properties:

- sizeInBytes: The remaining quota size in bytes (maximum 3KB).
- numKeys: The remaining quota for the number of keys (maximum 20 keys).

##### numKeys

• **numKeys**: `number`

##### sizeInBytes

• **sizeInBytes**: `number`

## Methods

### `[iterator]`()

• **\[iterator\]**(): `Iterator`<[`string`, `string`], `any`, `any`\>

#### Returns

`Iterator`<[`string`, `string`], `any`, `any`\>

an iterator for all the private metadata entries on the node.
The iterator yields the metadata key-value pairs.

---

### clear()

• **clear**(): `void`

Clears all private metadata entries on the node.

#### Returns

`void`

---

### getItem()

• **getItem**(`key`): `undefined` \| `string`

Retrieves the private metadata value for the specified key on the node.

#### Parameters

• **key**: `string`

The key of the private metadata entry to retrieve.

#### Returns

`undefined` \| `string`

The value of the private metadata entry.

---

### keys()

• **keys**(): `string`[]

#### Returns

`string`[]

an array of all keys for the private metadata entries on the node.

---

### removeItem()

• **removeItem**(`key`): `void`

Removes a single private metadata entry on the node.

#### Parameters

• **key**: `string`

The key of the private metadata entry to remove.

#### Returns

`void`

---

### setItem()

• **setItem**(`key`, `value`): `void`

Sets a private metadata entry on the node.

#### Parameters

• **key**: `string`

The key for the private metadata entry.

• **value**: `string`

The value for the private metadata entry.

#### Returns

`void`
[@express-document-sdk](../overview.md) / ArtboardList

# Class: ArtboardList

ArtboardList represents an ordered list of ArtboardNodes arranged in a timeline sequence, where they are called "scenes."
All items in the list are children of a single [PageNode](PageNode.md).

ArtboardList also provides APIs for adding/removing artboards from the page. ArtboardList is never empty: it is illegal to
remove the last remaining artboard from the list.

## Extends

-   [`RestrictedItemList`](RestrictedItemList.md)<[`ArtboardNode`](ArtboardNode.md)\>

## Accessors

### first

• `get` **first**(): `undefined` \| `T`

First item in this list, or undefined if list is empty.

#### Returns

`undefined` \| `T`

---

### last

• `get` **last**(): `undefined` \| `T`

Last item in this list, or undefined if list is empty.

#### Returns

`undefined` \| `T`

---

### length

• `get` **length**(): `number`

Number of items in this list.

#### Returns

`number`

## Methods

### `[iterator]`()

• **\[iterator\]**(): `Iterator`<[`ArtboardNode`](ArtboardNode.md), `any`, `any`\>

Iterates over all the items in this list. Mutations that occur mid-iteration are not reflected by the iterator.

#### Returns

`Iterator`<[`ArtboardNode`](ArtboardNode.md), `any`, `any`\>

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`[iterator]`](RestrictedItemList.md#iterator)

---

### addArtboard()

• **addArtboard**(): [`ArtboardNode`](ArtboardNode.md)

Create a new artboard and add it to the end of the list. The artboard size is the same as others on this page. The
artboard background is set to default fill color DEFAULT_ARTBOARD_FILL_COLOR. The new artboard becomes the
default target for newly inserted content (see insertionParent) and the timeline advances to show this artboard
in the current viewport.

#### Returns

[`ArtboardNode`](ArtboardNode.md)

the newly added artboard.

---

### indexOf()

• **indexOf**(`item`): `number`

Get index of item in list.

#### Parameters

• **item**: [`ArtboardNode`](ArtboardNode.md)

#### Returns

`number`

index number, or -1 if item isn't in this list.

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`indexOf`](RestrictedItemList.md#indexof)

---

### item()

• **item**(`index`): `undefined` \| [`ArtboardNode`](ArtboardNode.md)

Returns item at the given index, or undefined if index is out of range.

#### Parameters

• **index**: `number`

Zero-based index

#### Returns

`undefined` \| [`ArtboardNode`](ArtboardNode.md)

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`item`](RestrictedItemList.md#item)

---

### moveAfter()

• **moveAfter**(`item`, `after`): `void`

Move `item` so it is immediately after `after` in this list: places `item` at the index one higher than `after`.
Depending on the position in the list `item` originally occupied, some other items in the list may shift to higher
or lower indices as a result. No-op if both arguments are the same item.

#### Parameters

• **item**: [`ArtboardNode`](ArtboardNode.md)

• **after**: [`ArtboardNode`](ArtboardNode.md)

#### Returns

`void`

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`moveAfter`](RestrictedItemList.md#moveafter)

#### Throws

An error if either argument is not contained in this list.

---

### moveBefore()

• **moveBefore**(`item`, `before`): `void`

Move `item` so it is immediately before `before` in this list: places `item` at the index that `before` used
to occupy. Depending on the position in the list `item` originally occupied, some other items in the list may
shift to higher or lower indices as a result. No-op if both arguments are the same item.

#### Parameters

• **item**: [`ArtboardNode`](ArtboardNode.md)

• **before**: [`ArtboardNode`](ArtboardNode.md)

#### Returns

`void`

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`moveBefore`](RestrictedItemList.md#movebefore)

#### Throws

An error if either argument is not contained in this list.

---

### remove()

• **remove**(...`items`): `void`

Remove the items from the list. The items need not be contiguous.

#### Parameters

• ...**items**: [`ArtboardNode`](ArtboardNode.md)[]

#### Returns

`void`

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`remove`](RestrictedItemList.md#remove)

#### Throws

If any of the items are not in the list, or if it is illegal to remove any of the items from this parent.

---

### toArray()

• **toArray**(): readonly [`ArtboardNode`](ArtboardNode.md)[]

All items in the list, as a static array. Mutations that occur later are not reflected in an array returned earlier.

#### Returns

readonly [`ArtboardNode`](ArtboardNode.md)[]

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`toArray`](RestrictedItemList.md#toarray)
[@express-document-sdk](../overview.md) / ArtboardNode

# Class: ArtboardNode

An ArtboardNode represents an artboard object in the scenegraph. All user visual content must be contained on an artboard.
Artboards are always contained on a [PageNode](PageNode.md); when a page contains multiple artboards, the artboards represent
"scenes" in a linear timeline sequence.

To create a new artboard, see [ArtboardList.addArtboard](ArtboardList.md#addartboard).

Please note that creating and deleting an artboard in a single frame will crash the editor.

## Extends

-   [`VisualNode`](VisualNode.md)

## Implements

-   [`IRectangularNode`](../interfaces/IRectangularNode.md)
-   [`ContainerNode`](../interfaces/ContainerNode.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of an Artboard are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### children

• `get` **children**(): [`ItemList`](ItemList.md)<[`Node`](Node.md)\>

The node's children. Use the methods on this ItemList object to get, add, and remove children.

#### Returns

[`ItemList`](ItemList.md)<[`Node`](Node.md)\>

---

### fill

• `get` **fill**(): `Readonly`<[`Fill`](../interfaces/Fill.md)\>

• `set` **fill**(`fill`): `void`

The background fill of the artboard. Artboards must always have a fill.

#### Parameters

• **fill**: [`Fill`](../interfaces/Fill.md)

#### Returns

`Readonly`<[`Fill`](../interfaces/Fill.md)\>

---

### height

• `get` **height**(): `number`

The height of the artboard.

#### Returns

`number`

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### parent

• `get` **parent**(): `undefined` \| [`PageNode`](PageNode.md)

The node's parent. Undefined if the node is an orphan.

#### Returns

`undefined` \| [`PageNode`](PageNode.md)

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

---

### width

• `get` **width**(): `number`

The width of the artboard.

#### Returns

`number`

## Methods

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Implementation of

[`ContainerNode`](../interfaces/ContainerNode.md).[`localPointInNode`](../interfaces/ContainerNode.md#localpointinnode)

#### Inherited from

[`VisualNode`](VisualNode.md).[`localPointInNode`](VisualNode.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Implementation of

[`ContainerNode`](../interfaces/ContainerNode.md).[`removeFromParent`](../interfaces/ContainerNode.md#removefromparent)

#### Inherited from

[`VisualNode`](VisualNode.md).[`removeFromParent`](VisualNode.md#removefromparent)
[@express-document-sdk](../overview.md) / AvailableFont

# Class: AvailableFont

Font the current user has access or licensing permissions to create / edit content with.

## Extends

-   [`BaseFont`](BaseFont.md)

## Accessors

### availableForEditing

• `get` **availableForEditing**(): `true`

Whether the current user has permission to create / edit content using this font.

#### Returns

`true`

---

### family

• `get` **family**(): `string`

The font family containing the font.

#### Returns

`string`

---

### isPremium

• `get` **isPremium**(): `boolean`

Whether the font is a premium Adobe font.

#### Returns

`boolean`

---

### postscriptName

• `get` **postscriptName**(): `string`

The PostScript name of the font.

#### Returns

`string`

---

### style

• `get` **style**(): `string`

The style of the font within the family.

#### Returns

`string`
[@express-document-sdk](../overview.md) / BaseFont

# Class: `abstract` BaseFont

Represents a font that is able to be rendered within this document. However, the user may not have edit permissions for
all such fonts.

## Extended by

-   [`AvailableFont`](AvailableFont.md)
-   [`UnavailableFont`](UnavailableFont.md)

## Accessors

### availableForEditing

• `get` `abstract` **availableForEditing**(): `boolean`

Whether the current user has permission to create / edit content using this font.

#### Returns

`boolean`

---

### family

• `get` **family**(): `string`

The font family containing the font.

#### Returns

`string`

---

### postscriptName

• `get` **postscriptName**(): `string`

The PostScript name of the font.

#### Returns

`string`

---

### style

• `get` **style**(): `string`

The style of the font within the family.

#### Returns

`string`
[@express-document-sdk](../overview.md) / BaseNode

# Class: BaseNode

A "node" represents an object in the scenegraph, the document's visual content tree. This base class includes only the
most fundamental nonvisual properties that even nodes near the top of the document structure share (such as PageNode).
The more tangible visual content typically extends the richer Node class which extends BaseNode with additional
properties.

## Extended by

-   [`ExpressRootNode`](ExpressRootNode.md)
-   [`PageNode`](PageNode.md)
-   [`VisualNode`](VisualNode.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`BaseNode`](BaseNode.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

Although BaseNode's allChildren may yield other BaseNodes, the subclasses Node and ArtboardNode override allChildren
to guarantee all their children are full-fledged Node instances.

#### Returns

`Readonly`<`Iterable`<[`BaseNode`](BaseNode.md), `any`, `any`\>\>

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

## Methods

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`
[@express-document-sdk](../overview.md) / ColorUtils

# Class: ColorUtils

Utility methods for working with color values.

## Methods

### fromHex()

• **fromHex**(`hex`): [`Color`](../interfaces/Color.md)

Create a new color from its equivalent RGBA hex representation. Can specify in 6 digits (RRGGBB) or 8 digits
(RRGGBBAA), uppercase or lowercase, with or without leading "#". Alpha defaults to FF (100% opaque) if ommitted.

#### Parameters

• **hex**: `string`

The color represented as a hexadecimal string.

#### Returns

[`Color`](../interfaces/Color.md)

A new color value matching the given hex string.

#### Throws

if the hex string cannot be parsed.

---

### fromRGB()

#### fromRGB(red, green, blue, alpha)

• **fromRGB**(`red`, `green`, `blue`, `alpha`?): [`Color`](../interfaces/Color.md)

Create a new color object with the given RGBA values.

##### Parameters

• **red**: `number`

The red channel, from 0 - 1.

• **green**: `number`

The green channel, from 0 - 1.

• **blue**: `number`

The blue channel, from 0 - 1.

• **alpha?**: `number`

Optional alpha channel, from 0 - 1. Defaults to 1 (opaque).

##### Returns

[`Color`](../interfaces/Color.md)

A new color object.

#### fromRGB(color)

• **fromRGB**(`color`): [`Color`](../interfaces/Color.md)

Create a new color object given a partial color object where the alpha field may be missing.

##### Parameters

• **color**

Partial color object. Alpha defaults to 1 (opaque).

• **color.alpha?**: `number`

• **color.blue**: `number`

• **color.green**: `number`

• **color.red**: `number`

##### Returns

[`Color`](../interfaces/Color.md)

A new color object with all fields present.

---

### toHex()

• **toHex**(`color`): `string`

Get the color in 8-digit hex "#RRGGBBAA" format.

#### Parameters

• **color**: [`Color`](../interfaces/Color.md)

#### Returns

`string`
[@express-document-sdk](../overview.md) / ComplexShapeNode

# Class: ComplexShapeNode

A ComplexShapeNode is a complex prepackaged shape that appears as a leaf node in the UI, even if it is composed
of multiple separate paths.

## Extends

-   [`FillableNode`](FillableNode.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### fill

• `get` **fill**(): `undefined` \| `Readonly`<[`Fill`](../interfaces/Fill.md)\>

• `set` **fill**(`fill`): `void`

The fill applied to the shape, if any.

#### Parameters

• **fill**: `undefined` \| [`Fill`](../interfaces/Fill.md)

#### Returns

`undefined` \| `Readonly`<[`Fill`](../interfaces/Fill.md)\>

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### stroke

• `get` **stroke**(): `undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

• `set` **stroke**(`stroke`): `void`

The stroke applied to the shape, if any.
Only [SolidColorStroke](../interfaces/SolidColorStroke.md) values are supported by the setter, but the "type" field is optional
for backward compatibility. Throws if another type is provided.

#### Parameters

• **stroke**: `undefined` \| [`SolidColorStrokeWithOptionalType`](../type-aliases/SolidColorStrokeWithOptionalType.md)

#### Returns

`undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`FillableNode`](FillableNode.md).[`boundsInNode`](FillableNode.md#boundsinnode)

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`FillableNode`](FillableNode.md).[`localPointInNode`](FillableNode.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`FillableNode`](FillableNode.md).[`removeFromParent`](FillableNode.md#removefromparent)

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`FillableNode`](FillableNode.md).[`setPositionInParent`](FillableNode.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`FillableNode`](FillableNode.md).[`setRotationInParent`](FillableNode.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / Context

# Class: Context

Contains the user's current selection state, indicating the content they are focused on.

## Accessors

### currentPage

• `get` **currentPage**(): [`PageNode`](PageNode.md)

#### Returns

[`PageNode`](PageNode.md)

The currently viewed page.

---

### hasSelection

• `get` **hasSelection**(): `boolean`

#### Returns

`boolean`

false if the current editable selection does not contain any nodes, otherwise true.

---

### insertionParent

• `get` **insertionParent**(): [`ContainerNode`](../interfaces/ContainerNode.md)

#### Returns

[`ContainerNode`](../interfaces/ContainerNode.md)

the preferred parent to insert newly added content into (i.e., the location content would get inserted if a
user were to Paste or use the Shapes panel in the UI). This will vary depending on the user's current selection and
other UI state.

---

### selection

• `get` **selection**(): readonly [`Node`](Node.md)[]

• `set` **selection**(`nodes`): `void`

Sets the current selection to an array of [Node](Node.md).
Accepts a single node as a shortcut for a length-1 array `[node]` or
`undefined` as a shortcut for `[]`, which clears the selection.

Only node(s) that meet the following criteria can be selected:

- Nodes must be within the current artboard (nodes outside the active artboard are filtered out).
- A node cannot be selected if its ancestor is also selected (descendants are filtered out).
- Locked nodes are filtered out (but will still be included in selectionIncludingNonEditable).

#### Parameters

• **nodes**: `undefined` \| [`Node`](Node.md) \| readonly [`Node`](Node.md)[]

#### Returns

readonly [`Node`](Node.md)[]

the current selection. Nodes that are locked or otherwise non-editable are never included in the selection.

---

### selectionIncludingNonEditable

• `get` **selectionIncludingNonEditable**(): readonly [`Node`](Node.md)[]

#### Returns

readonly [`Node`](Node.md)[]

the current selection _and_ any locked nodes the user has attempted to select at the same time. This can
happen for example if the user clicks on a locked node or if the user drags a selection marquee that overlaps
locked nodes in addition to regular unlocked nodes.

## Methods

### off()

• **off**(`eventName`, `handlerId`): `void`

Unregisters handlers for editor events like selection change.

#### Parameters

• **eventName**: [`selectionChange`](../enumerations/EditorEvent.md#selectionchange)

an editor event name.

• **handlerId**: `string`

a unique ID returned by `editor.context.on` API.
Callback that was previously registered will be removed and will no more be invoked when the event occurs.

#### Returns

`void`

---

### on()

• **on**(`eventName`, `callback`): `string`

Registers a handler for editor events such as selection change.
The registered callback will be invoked when the specified event occurs.
Note: Do not attempt to make changes to the document in response to a selection change callback because it may destabilize the application.

#### Parameters

• **eventName**: [`selectionChange`](../enumerations/EditorEvent.md#selectionchange)

an editor event name.

• **callback**: [`EditorEventHandler`](../type-aliases/EditorEventHandler.md)

a callback to be registered for an editor event.

#### Returns

`string`

a unique ID for the registered event handler.
[@express-document-sdk](../overview.md) / Editor

# Class: Editor

Entry point for APIs that read or modify the document's content.

## Accessors

### context

• `get` **context**(): [`Context`](Context.md)

User's current selection context

#### Returns

[`Context`](Context.md)

---

### documentRoot

• `get` **documentRoot**(): [`ExpressRootNode`](ExpressRootNode.md)

#### Returns

[`ExpressRootNode`](ExpressRootNode.md)

the root of the document.

## Methods

### createEllipse()

• **createEllipse**(): [`EllipseNode`](EllipseNode.md)

#### Returns

[`EllipseNode`](EllipseNode.md)

an ellipse node with default x/y radii, a black fill, and no initial stroke.
Transform values default to 0.

---

### createGroup()

• **createGroup**(): [`GroupNode`](GroupNode.md)

#### Returns

[`GroupNode`](GroupNode.md)

a group node.

---

### createImageContainer()

• **createImageContainer**(`bitmapData`, `options`): [`MediaContainerNode`](MediaContainerNode.md)

Creates a bitmap image, represented as a multi-node MediaContainerNode structure. Always creates a "full-frame,"
uncropped image initially, but cropping can be changed after it is created by modifying the properties of the
container's mediaRectangle and maskShape children.

Image creation involves some asynchronous steps. The image will be visible in this client almost instantly, but will
render as a gray placeholder on other clients until it has been uploaded to DCX and then downloaded by those clients.
This local client will act as having unsaved changes until the upload has finished.

#### Parameters

• **bitmapData**: [`BitmapImage`](../interfaces/BitmapImage.md)

BitmapImage resource (e.g. returned from [loadBitmapImage](Editor.md#loadbitmapimage)).

• **options**= `{}`

Additional configuration: - initialSize - Size the image is displayed at. Must have the same aspect ratio as bitmapData. Defaults to the
size the image would be created at by a UI drag-drop gesture (typically the image's full size, but scaled down
if needed to stay below an application-defined size cap).

• **options.initialSize?**: [`RectangleGeometry`](../interfaces/RectangleGeometry.md)

#### Returns

[`MediaContainerNode`](MediaContainerNode.md)

MediaContainerNode representing the top container node of the multi-node structure.

---

### createLine()

• **createLine**(): [`LineNode`](LineNode.md)

#### Returns

[`LineNode`](LineNode.md)

a line node with default start point and end point and a default stroke.
Transform values default to 0.

---

### createPath()

• **createPath**(`path`): [`PathNode`](PathNode.md)

#### Parameters

• **path**: `string`

a string representing any [SVG path element](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths).
Note that the path data will be normalized, and therefore the `path` getter may return a different SVG string from the path creation input.
For example, "M 10 80 Q 52.5 10, 95 80 T 180 80" becomes "M 10 80 C 38.33 33.33 66.67 33.33 95 80...".
Throws if the input is empty or is not legal SVG path syntax.

#### Returns

[`PathNode`](PathNode.md)

a path node with a default stroke and no initial fill.

---

### createRectangle()

• **createRectangle**(): [`RectangleNode`](RectangleNode.md)

#### Returns

[`RectangleNode`](RectangleNode.md)

a rectangle node with default width and height, a black fill, and no initial stroke.
Transform values default to 0.

---

### createText()

• **createText**(): [`TextNode`](TextNode.md)

#### Returns

[`TextNode`](TextNode.md)

a text node with default styles. The text content is initially empty, so the text node will be
invisible until its `fullContent` property's `text` is set. Creates point text, so the node's width will automatically
adjust to accommodate whatever text is set.

Note: the registration point of this text node is not guaranteed to be at the top-left of the bounding box of its
insertion parent. Recommend using `setPositionInParent` over `translation` to set the position.

---

### loadBitmapImage()

• **loadBitmapImage**(`bitmapData`): `Promise`<[`BitmapImage`](../interfaces/BitmapImage.md)\>

Creates a bitmap image resource in the document, which can be displayed in the scenegraph by passing it to [createImageContainer](Editor.md#createimagecontainer)
to create a MediaContainerNode. The same BitmapImage can be used to create multiple MediaContainerNodes.

Because the resulting BitmapImage is returned asynchronously, to use it you must schedule an edit lambda to run at a
safe later time in order to call [createImageContainer](Editor.md#createimagecontainer). See [queueAsyncEdit](Editor.md#queueasyncedit).

Further async steps to upload image resource data may continue in the background after this call's Promise resolves,
but the resulting BitmapImage can be used right away (via the queue API noted above). The local client will act as
having unsaved changes until all the upload steps have finished.

#### Parameters

• **bitmapData**: `Blob`

Encoded image data in PNG or JPEG format.

#### Returns

`Promise`<[`BitmapImage`](../interfaces/BitmapImage.md)\>

---

### makeColorFill()

• **makeColorFill**(`color`): [`ColorFill`](../interfaces/ColorFill.md)

Convenience helper to create a complete ColorFill value given just its color.

#### Parameters

• **color**: [`Color`](../interfaces/Color.md)

The color to use for the fill.

#### Returns

[`ColorFill`](../interfaces/ColorFill.md)

---

### makeStroke()

• **makeStroke**(`options`?): [`SolidColorStroke`](../interfaces/SolidColorStroke.md)

Convenience helper to create a complete SolidColorStroke value given just a
subset of its fields. All other fields are populated with default values.

See [SolidColorStroke](../interfaces/SolidColorStroke.md) for more details on the `options` fields. Defaults:

-   `color` has default value DEFAULT_STROKE_COLOR if none is provided.
-   `width` has default value DEFAULT_STROKE_WIDTH if none is provided.
-   `position` has default value `center` if none is provided.
-   `dashPattern` has default value [] if none is provided.
-   `dashOffset` has default value 0 if none is provided. This field is ignored
  if no `dashPattern` was provided.
-   `type` has default value SolidColorStroke.type if none is provided. This field
   shouldn't be set to any other value.

#### Parameters

• **options?**: `Partial`<[`SolidColorStroke`](../interfaces/SolidColorStroke.md)\>

#### Returns

[`SolidColorStroke`](../interfaces/SolidColorStroke.md)

a stroke configured with the given options.

---

### queueAsyncEdit()

• **queueAsyncEdit**(`lambda`): `Promise`<`void`\>

Enqueues a function to be run at a later time when edits to the user's document may be performed. You can always edit
the document immediately when invoked in response to your add-on's UI code. However, if you delay to await an
asynchronous operation such as [loadBitmapImage](Editor.md#loadbitmapimage), any edits following this pause must be scheduled using
queueAsyncEdit(). This ensures the edit is properly tracked for saving and undo.

The delay before your edit function is executed is typically just a few milliseconds, so it will appear instantaneous
to users. However, note that queueAsyncEdit() will return _before_ your function has been run.
If you need to trigger any code after the edit has been performed, either include this in the lambda you are enqueuing
or await the Promise returned by queueAsyncEdit().

Generally, calling any setter or method is treated as an edit; but simple getters may be safely called at any time.

Example of typical usage:

```js
// Assume insertImage() is called from your UI code, and given a Blob containing image data
async function insertImage(blob) {
    // This function was invoked from the UI iframe, so we can make any edits we want synchronously here.
    // Initially load the bitmap - an async operation
    const bitmapImage = await editor.loadBitmapImage(blob);

    // Execution doesn't arrive at this line until an async delay, due to the Promise 'await' above

    // Further edits need to be queued to run at a safe time
    editor.queueAsyncEdit(() => {
         // Create scenenode to display the image, and add it to the current artboard
         const mediaContainer = editor.createImageContainer(bitmapImage);
         editor.context.insertionParent.children.append(mediaContainer);
    });
}
```

#### Parameters

• **lambda**

a function which edits the document model.

#### Returns

`Promise`<`void`\>

a Promise that resolves when the lambda has finished running, or rejects if the lambda throws an error.
[@express-document-sdk](../overview.md) / EllipseNode

# Class: EllipseNode

An EllipseNode represents an ellipse or circle shape in the scenegraph.

To create new ellipse, see [Editor.createEllipse](Editor.md#createellipse).

## Extends

-   [`FillableNode`](FillableNode.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### fill

• `get` **fill**(): `undefined` \| `Readonly`<[`Fill`](../interfaces/Fill.md)\>

• `set` **fill**(`fill`): `void`

The fill applied to the shape, if any.

#### Parameters

• **fill**: `undefined` \| [`Fill`](../interfaces/Fill.md)

#### Returns

`undefined` \| `Readonly`<[`Fill`](../interfaces/Fill.md)\>

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### rx

• `get` **rx**(): `number`

The radius of the ellipse on the x-axis.

• `set` **rx**(`value`): `void`

Set the ellipse radius on the x-axis.
Must be at least MIN_DIMENSION / 2.

#### Parameters

• **value**: `number`

#### Returns

`number`

---

### ry

• `get` **ry**(): `number`

The radius of the ellipse on the y-axis.

• `set` **ry**(`value`): `void`

Set the ellipse radius on the y-axis.
Must be at least MIN_DIMENSION / 2.

#### Parameters

• **value**: `number`

#### Returns

`number`

---

### stroke

• `get` **stroke**(): `undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

• `set` **stroke**(`stroke`): `void`

The stroke applied to the shape, if any.
Only [SolidColorStroke](../interfaces/SolidColorStroke.md) values are supported by the setter, but the "type" field is optional
for backward compatibility. Throws if another type is provided.

#### Parameters

• **stroke**: `undefined` \| [`SolidColorStrokeWithOptionalType`](../type-aliases/SolidColorStrokeWithOptionalType.md)

#### Returns

`undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`FillableNode`](FillableNode.md).[`boundsInNode`](FillableNode.md#boundsinnode)

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`FillableNode`](FillableNode.md).[`localPointInNode`](FillableNode.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`FillableNode`](FillableNode.md).[`removeFromParent`](FillableNode.md#removefromparent)

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`FillableNode`](FillableNode.md).[`setPositionInParent`](FillableNode.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`FillableNode`](FillableNode.md).[`setRotationInParent`](FillableNode.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / ExpressRootNode

# Class: ExpressRootNode

An ExpressRootNode represents the root node of the document's "scenegraph" artwork tree. The root contains a collection
of [pages](ExpressRootNode.md#pages). Each page contains one or more artboards, arranged in a timeline sequence. All the visual content of
the document lies within those artboards.

The parent of ExpressRootNode is undefined, since it is the root of the document tree.

## Extends

-   [`BaseNode`](BaseNode.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`BaseNode`](BaseNode.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

Although BaseNode's allChildren may yield other BaseNodes, the subclasses Node and ArtboardNode override allChildren
to guarantee all their children are full-fledged Node instances.

#### Returns

`Readonly`<`Iterable`<[`BaseNode`](BaseNode.md), `any`, `any`\>\>

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### pages

• `get` **pages**(): [`PageList`](PageList.md)

The pages of the document. All visual content is contained on artboards within the pages.
To create a new page, see [PageList.addPage](PageList.md#addpage).

#### Returns

[`PageList`](PageList.md)

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

## Methods

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`BaseNode`](BaseNode.md).[`removeFromParent`](BaseNode.md#removefromparent)
[@express-document-sdk](../overview.md) / FillableNode

# Class: FillableNode

Base class for a Node that can have its own fill and stroke.

## Extends

-   [`StrokableNode`](StrokableNode.md)

## Extended by

-   [`ComplexShapeNode`](ComplexShapeNode.md)
-   [`EllipseNode`](EllipseNode.md)
-   [`PathNode`](PathNode.md)
-   [`RectangleNode`](RectangleNode.md)

## Implements

-   [`IFillableNode`](../interfaces/IFillableNode.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### fill

• `get` **fill**(): `undefined` \| `Readonly`<[`Fill`](../interfaces/Fill.md)\>

• `set` **fill**(`fill`): `void`

The fill applied to the shape, if any.

#### Parameters

• **fill**: `undefined` \| [`Fill`](../interfaces/Fill.md)

#### Returns

`undefined` \| `Readonly`<[`Fill`](../interfaces/Fill.md)\>

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### stroke

• `get` **stroke**(): `undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

• `set` **stroke**(`stroke`): `void`

The stroke applied to the shape, if any.
Only [SolidColorStroke](../interfaces/SolidColorStroke.md) values are supported by the setter, but the "type" field is optional
for backward compatibility. Throws if another type is provided.

#### Parameters

• **stroke**: `undefined` \| [`SolidColorStrokeWithOptionalType`](../type-aliases/SolidColorStrokeWithOptionalType.md)

#### Returns

`undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`StrokableNode`](StrokableNode.md).[`boundsInNode`](StrokableNode.md#boundsinnode)

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`StrokableNode`](StrokableNode.md).[`localPointInNode`](StrokableNode.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`StrokableNode`](StrokableNode.md).[`removeFromParent`](StrokableNode.md#removefromparent)

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`StrokableNode`](StrokableNode.md).[`setPositionInParent`](StrokableNode.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`StrokableNode`](StrokableNode.md).[`setRotationInParent`](StrokableNode.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / Fonts

# Class: Fonts

The Fonts class provides methods to work with fonts.

## Methods

### fromPostscriptName()

• **fromPostscriptName**(`postscriptName`): `Promise`<`undefined` \| [`AvailableFont`](AvailableFont.md)\>

Get an [AvailableFont](AvailableFont.md) that exactly matches the given PostScript name, if any. Only fonts that the user has permission to use
for editing content are returned, so the result of this call is always safe to apply to a [TextContentModel](TextContentModel.md)'s styles.

#### Parameters

• **postscriptName**: `string`

The PostScript name of the font.

#### Returns

`Promise`<`undefined` \| [`AvailableFont`](AvailableFont.md)\>

The Font object if found and available for editing, otherwise undefined.
[@express-document-sdk](../overview.md) / GridCellNode

# Class: GridCellNode

A GridCellNode represents the MediaContainerNode aspect of a grid cell. Unlike other MediaContainerNodes,
GridCellNodes cannot be translated or rotated directly. This implementation translates and rotates the
MediaRectangle child of the GridCellNode when those actions are applied.

## Extends

-   [`MediaContainerNode`](MediaContainerNode.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### maskShape

• `get` **maskShape**(): [`FillableNode`](FillableNode.md)

The mask used for cropping/clipping the media. The bounds of this shape are entire visible bounds of the container.
The shape's geometric properties (position, rotation, size, etc.) can be changed, but it cannot be replaced by a
different shape via this API.

#### Returns

[`FillableNode`](FillableNode.md)

---

### mediaRectangle

• `get` **mediaRectangle**(): [`Node`](Node.md) \| [`ImageRectangleNode`](ImageRectangleNode.md)

The rectangular node representing the entire, uncropped bounds of the media (e.g. image, GIFs, or video). The media's position and
rotation can be changed, but it cannot be resized yet via this API. Media types other than images will yield a plain Node object
for now.

#### Returns

[`Node`](Node.md) \| [`ImageRectangleNode`](ImageRectangleNode.md)

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`MediaContainerNode`](MediaContainerNode.md).[`boundsInNode`](MediaContainerNode.md#boundsinnode)

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`MediaContainerNode`](MediaContainerNode.md).[`localPointInNode`](MediaContainerNode.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`MediaContainerNode`](MediaContainerNode.md).[`removeFromParent`](MediaContainerNode.md#removefromparent)

---

### replaceMedia()

• **replaceMedia**(`media`): `void`

Replace existing media inline. The new media is sized to completely fill the bounds of the existing maskShape; if the
media's aspect ratio differs from the maskShape's, the media will be cropped by the maskShape on either the left/right
or top/bottom edges. Currently only supports images as the new media, but previous media can be of any type.

#### Parameters

• **media**: [`BitmapImage`](../interfaces/BitmapImage.md)

New content to display. Currently must be a [BitmapImage](../interfaces/BitmapImage.md).

#### Returns

`void`

#### Inherited from

[`MediaContainerNode`](MediaContainerNode.md).[`replaceMedia`](MediaContainerNode.md#replacemedia)

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`MediaContainerNode`](MediaContainerNode.md).[`setPositionInParent`](MediaContainerNode.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`MediaContainerNode`](MediaContainerNode.md).[`setRotationInParent`](MediaContainerNode.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / GridLayoutNode

# Class: GridLayoutNode

A GridLayoutNode represents a grid layout in the scenegraph. The GridLayoutNode is used to create
a layout grid that other content can be placed into.

APIs to create a new grid layout are not yet available.

## Extends

-   [`Node`](Node.md)

## Implements

-   `Readonly`<[`IRectangularNode`](../interfaces/IRectangularNode.md)\>

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

The Grid's regular children. Does not include rectangles and skips over media constainer nodes to return fill grandchildren.
Grid Cells are ordered by the y and then x position of their top left corner, i.e. left to right and top to bottom.
The children cannot be added or removed.

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### fill

• `get` **fill**(): `Readonly`<[`Fill`](../interfaces/Fill.md)\>

• `set` **fill**(`fill`): `void`

The background fill of the GridLayout.

#### Parameters

• **fill**: [`Fill`](../interfaces/Fill.md)

#### Returns

`Readonly`<[`Fill`](../interfaces/Fill.md)\>

---

### height

• `get` **height**(): `number`

The height of the node.

#### Returns

`number`

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

---

### width

• `get` **width**(): `number`

The width of the node.

#### Returns

`number`

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`Node`](Node.md).[`boundsInNode`](Node.md#boundsinnode)

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`Node`](Node.md).[`localPointInNode`](Node.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`removeFromParent`](Node.md#removefromparent)

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setPositionInParent`](Node.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setRotationInParent`](Node.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / GroupNode

# Class: GroupNode

A GroupNode represents a Group object in the scenegraph, which has a collection of generic children as well as a separate,
optional vector mask child.

To create new group, see [Editor.createGroup](Editor.md#creategroup).

## Extends

-   [`Node`](Node.md)

## Implements

-   [`ContainerNode`](../interfaces/ContainerNode.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

Note: If this group has a maskShape, group's bounds are always identical to the maskShape's, regardless of the
group's other content.

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### children

• `get` **children**(): [`ItemList`](ItemList.md)<[`Node`](Node.md)\>

The Group's regular children. Does not include the maskShape if one is present.
Use the methods on this ItemList object to get, add, and remove children.

#### Returns

[`ItemList`](ItemList.md)<[`Node`](Node.md)\>

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### maskShape

• `get` **maskShape**(): `undefined` \| [`FillableNode`](FillableNode.md)

A vector shape that acts as a clipping mask for the content of this group. The mask node is separate from the Group's
generic 'children' collection, though both are part of the overall 'allChildren' of this Group.

• `set` **maskShape**(`mask`): `void`

If set to a vector shape, adds a mask or replaces the existing mask on this Group.
If set to undefined, removes any mask that was previously set on this Group.

#### Throws

if the given node type cannot be used as a vector mask.

#### Parameters

• **mask**: `undefined` \| [`FillableNode`](FillableNode.md)

#### Returns

`undefined` \| [`FillableNode`](FillableNode.md)

undefined if no mask is set on this group.

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`Node`](Node.md).[`boundsInNode`](Node.md#boundsinnode)

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Implementation of

[`ContainerNode`](../interfaces/ContainerNode.md).[`localPointInNode`](../interfaces/ContainerNode.md#localpointinnode)

#### Inherited from

[`Node`](Node.md).[`localPointInNode`](Node.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Implementation of

[`ContainerNode`](../interfaces/ContainerNode.md).[`removeFromParent`](../interfaces/ContainerNode.md#removefromparent)

#### Inherited from

[`Node`](Node.md).[`removeFromParent`](Node.md#removefromparent)

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setPositionInParent`](Node.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setRotationInParent`](Node.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / ImageRectangleNode

# Class: ImageRectangleNode

ImageRectangleNode is a rectangular node that displays the image media part of a MediaContainerNode. It can only exist
within that container parent. Cropping can be adjusted by changing this media's position/rotation (as well as its mask
shape sibling node).

ImageRectangleNodes cannot be created directly; use [Editor.createImageContainer](Editor.md#createimagecontainer) to create the entire
container structure together.

## Extends

-   [`Node`](Node.md)

## Implements

-   `Readonly`<[`IRectangularNode`](../interfaces/IRectangularNode.md)\>

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### height

• `get` **height**(): `number`

Current height of the "full frame" image rectangle, which may not be fully visible due to cropping/clipping by the
enclosing media container's maskShape. This size may be different from the original bitmap's size in pixels, but
will always match its aspect ratio.

#### Returns

`number`

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

---

### width

• `get` **width**(): `number`

Current width of the "full frame" image rectangle, which may not be fully visible due to cropping/clipping by the
enclosing media container's maskShape. This size may be different from the original bitmap's size in pixels, but
will always match its aspect ratio.

#### Returns

`number`

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`Node`](Node.md).[`boundsInNode`](Node.md#boundsinnode)

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`Node`](Node.md).[`localPointInNode`](Node.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`removeFromParent`](Node.md#removefromparent)

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setPositionInParent`](Node.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setRotationInParent`](Node.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / ItemList

# Class: ItemList<T\>

ItemList represents an ordered list of API objects, representing items that are all children of the
same parent node. (The reverse is not necessarily true, however: this list might not include all
children that exist in the parent node. See [Node.allChildren](Node.md#allchildren) for details).

ItemList also provides APIs for manipulating the list by adding items to the parent or removing items from the parent.

This class is used in different places for various types of items, including Nodes, Fills, and Strokes.

## Extends

-   [`RestrictedItemList`](RestrictedItemList.md)<`T`\>

## Type parameters

• **T** _extends_ [`ListItem`](../interfaces/ListItem.md)

## Accessors

### first

• `get` **first**(): `undefined` \| `T`

First item in this list, or undefined if list is empty.

#### Returns

`undefined` \| `T`

---

### last

• `get` **last**(): `undefined` \| `T`

Last item in this list, or undefined if list is empty.

#### Returns

`undefined` \| `T`

---

### length

• `get` **length**(): `number`

Number of items in this list.

#### Returns

`number`

## Methods

### `[iterator]`()

• **\[iterator\]**(): `Iterator`<`T`, `any`, `any`\>

Iterates over all the items in this list. Mutations that occur mid-iteration are not reflected by the iterator.

#### Returns

`Iterator`<`T`, `any`, `any`\>

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`[iterator]`](RestrictedItemList.md#iterator)

---

### append()

• **append**(...`items`): `void`

Add one or more items to the end of the list. The last argument will become the last item in this list. Items are
removed from their previous parent, if any – or if an item is already in _this_ list, its index is simply changed.

#### Parameters

• ...**items**: `T`[]

#### Returns

`void`

#### Throws

- if item has a different parent and item is a [TextNode](TextNode.md) that's a part of a Text Flow, or if item's children subtree contains a TextNode who is a part of a Text Flow.

---

### clear()

• **clear**(): `void`

Remove all items from this list. No-op if list is already empty.

#### Returns

`void`

---

### indexOf()

• **indexOf**(`item`): `number`

Get index of item in list.

#### Parameters

• **item**: `T`

#### Returns

`number`

index number, or -1 if item isn't in this list.

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`indexOf`](RestrictedItemList.md#indexof)

---

### insertAfter()

• **insertAfter**(`newItem`, `after`): `void`

Insert `newItem` so it is immediately after `after` in this list: places `newItem` at the index one higher than `after`,
shifting all later items to higher indices (the index of `after` remains unchanged). `newItem` is removed from its previous parent,
if any – or if it's already in _this_ list, its index is simply changed. No-op if both arguments are the same item.

#### Parameters

• **newItem**: `T`

• **after**: `T`

#### Returns

`void`

#### Throws

- if newItem has a different parent and it is a [TextNode](TextNode.md) that's a part of a Text Flow, or if newItem's children subtree contains a TextNode who is a part of a Text Flow.

---

### insertBefore()

• **insertBefore**(`newItem`, `before`): `void`

Insert `newItem` so it is immediately before `before` in this list: places `newItem` at the index that `before` used
to occupy, shifting `before` and all later items to higher indices. `newItem` is removed from its previous parent,
if any – or if it's already in _this_ list, its index is simply changed. No-op if both arguments are the same item.

#### Parameters

• **newItem**: `T`

• **before**: `T`

#### Returns

`void`

#### Throws

- if newItem has a different parent and it is a [TextNode](TextNode.md) that's a part of a Text Flow, or if newItem's children subtree contains a TextNode who is a part of a Text Flow.

---

### item()

• **item**(`index`): `undefined` \| `T`

Returns item at the given index, or undefined if index is out of range.

#### Parameters

• **index**: `number`

Zero-based index

#### Returns

`undefined` \| `T`

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`item`](RestrictedItemList.md#item)

---

### moveAfter()

• **moveAfter**(`item`, `after`): `void`

Move `item` so it is immediately after `after` in this list: places `item` at the index one higher than `after`.
Depending on the position in the list `item` originally occupied, some other items in the list may shift to higher
or lower indices as a result. No-op if both arguments are the same item.

#### Parameters

• **item**: `T`

• **after**: `T`

#### Returns

`void`

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`moveAfter`](RestrictedItemList.md#moveafter)

#### Throws

An error if either argument is not contained in this list.

---

### moveBefore()

• **moveBefore**(`item`, `before`): `void`

Move `item` so it is immediately before `before` in this list: places `item` at the index that `before` used
to occupy. Depending on the position in the list `item` originally occupied, some other items in the list may
shift to higher or lower indices as a result. No-op if both arguments are the same item.

#### Parameters

• **item**: `T`

• **before**: `T`

#### Returns

`void`

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`moveBefore`](RestrictedItemList.md#movebefore)

#### Throws

An error if either argument is not contained in this list.

---

### remove()

• **remove**(...`items`): `void`

Remove the items from the list. The items need not be contiguous.

#### Parameters

• ...**items**: `T`[]

#### Returns

`void`

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`remove`](RestrictedItemList.md#remove)

#### Throws

If any of the items are not in the list, or if it is illegal to remove any of the items from this parent.

---

### replace()

• **replace**(`oldItem`, `newItem`): `void`

Replace `oldItem` with `newItem` in this list. Throws if `oldItem` is not a member of this list.
`newItem` is removed from its previous parent, if any – or if it's already in _this_ list, its index is simply
changed. No-op if both arguments are the same item.

#### Parameters

• **oldItem**: `T`

• **newItem**: `T`

#### Returns

`void`

#### Throws

- if newItem has a different parent and newItem is a [TextNode](TextNode.md) that's a part of a Text Flow, or if newItem's children subtree contains a TextNode who is a part of a Text Flow.

---

### toArray()

• **toArray**(): readonly `T`[]

All items in the list, as a static array. Mutations that occur later are not reflected in an array returned earlier.

#### Returns

readonly `T`[]

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`toArray`](RestrictedItemList.md#toarray)
[@express-document-sdk](../overview.md) / LineNode

# Class: LineNode

A LineNode represents a simple vector line in the scenegraph – a single straight-line segment.

To create a new line, see [Editor.createLine](Editor.md#createline).

## Extends

-   [`StrokableNode`](StrokableNode.md)

## Properties

### DEFAULT_END_X

• `static` `readonly` **DEFAULT_END_X**: `100` = `100`

---

### DEFAULT_END_Y

• `static` `readonly` **DEFAULT_END_Y**: `100` = `100`

---

### DEFAULT_START_X

• `static` `readonly` **DEFAULT_START_X**: `0` = `0`

---

### DEFAULT_START_Y

• `static` `readonly` **DEFAULT_START_Y**: `0` = `0`

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### endArrowHeadType

• `get` **endArrowHeadType**(): [`ArrowHeadType`](../enumerations/ArrowHeadType.md)

The shape encapsulating the end of a line.

Returns [ArrowHeadType.none](../enumerations/ArrowHeadType.md#none) if there is no stroke on the line.

• `set` **endArrowHeadType**(`type`): `void`

The setter sets a default stroke on the line if it did not have one.

#### Throws

if the line's stroke is not a SolidColorStroke type.
More complex stroke types do not support arrowheads.

#### Parameters

• **type**: [`ArrowHeadType`](../enumerations/ArrowHeadType.md)

#### Returns

[`ArrowHeadType`](../enumerations/ArrowHeadType.md)

---

### endX

• `get` **endX**(): `number`

The end point on the x-axis in the parent's coordinate system. Modify using `setEndPoints()`.

#### Returns

`number`

---

### endY

• `get` **endY**(): `number`

The end point on the y-axis in the parent's coordinate system. Modify using `setEndPoints()`.

#### Returns

`number`

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### startArrowHeadType

• `get` **startArrowHeadType**(): [`ArrowHeadType`](../enumerations/ArrowHeadType.md)

The shape encapsulating the start of a line.

Returns [ArrowHeadType.none](../enumerations/ArrowHeadType.md#none) if there is no stroke on the line.

• `set` **startArrowHeadType**(`type`): `void`

The setter sets a default stroke on the line if it did not have one.

#### Throws

if the line's stroke is not a SolidColorStroke type.
More complex stroke types do not support arrowheads.

#### Parameters

• **type**: [`ArrowHeadType`](../enumerations/ArrowHeadType.md)

#### Returns

[`ArrowHeadType`](../enumerations/ArrowHeadType.md)

---

### startX

• `get` **startX**(): `number`

The start point on the x-axis in the parent's coordinate system. Modify using `setEndPoints()`.

#### Returns

`number`

---

### startY

• `get` **startY**(): `number`

The start point on the y-axis in the parent's coordinate system. Modify using `setEndPoints()`.

#### Returns

`number`

---

### stroke

• `get` **stroke**(): `undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

• `set` **stroke**(`stroke`): `void`

The stroke applied to the shape, if any.
Only [SolidColorStroke](../interfaces/SolidColorStroke.md) values are supported by the setter, but the "type" field is optional
for backward compatibility. Throws if another type is provided.

#### Parameters

• **stroke**: `undefined` \| [`SolidColorStrokeWithOptionalType`](../type-aliases/SolidColorStrokeWithOptionalType.md)

#### Returns

`undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`StrokableNode`](StrokableNode.md).[`boundsInNode`](StrokableNode.md#boundsinnode)

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`StrokableNode`](StrokableNode.md).[`localPointInNode`](StrokableNode.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`StrokableNode`](StrokableNode.md).[`removeFromParent`](StrokableNode.md#removefromparent)

---

### setEndPoints()

• **setEndPoints**(`startX`, `startY`, `endX`, `endY`): `void`

Set the start and end points of the line in its local coordinate space (which may
differ from its parent's coordinate space based on `transformMatrix`, i.e.
`rotation` and `translation`). The values passed in may be normalized
by this setter, shifting the node's translation and counter-shifting the start/end
points. Therefore, the start/end getters may return values different from the values
you passed into this setter, even though the line's visual bounds and appearance are
the same. Rotation is preserved.

#### Parameters

• **startX**: `number`

• **startY**: `number`

• **endX**: `number`

• **endY**: `number`

#### Returns

`void`

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`StrokableNode`](StrokableNode.md).[`setPositionInParent`](StrokableNode.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`StrokableNode`](StrokableNode.md).[`setRotationInParent`](StrokableNode.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / MediaContainerNode

# Class: MediaContainerNode

A MediaContainerNode is a multi-node construct that displays media (such as images or video) with optional cropping and
clipping to a shape mask. The underlying media asset is always rectangular, but the final appearance of this node is
determined by the maskShape which is not necessarily a rectangle.

To create new media container for a bitmap image, see [Editor.createImageContainer](Editor.md#createimagecontainer). APIs for creating a
container with other content, such as videos, are not yet available.

## Extends

-   [`Node`](Node.md)

## Extended by

-   [`GridCellNode`](GridCellNode.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### maskShape

• `get` **maskShape**(): [`FillableNode`](FillableNode.md)

The mask used for cropping/clipping the media. The bounds of this shape are entire visible bounds of the container.
The shape's geometric properties (position, rotation, size, etc.) can be changed, but it cannot be replaced by a
different shape via this API.

#### Returns

[`FillableNode`](FillableNode.md)

---

### mediaRectangle

• `get` **mediaRectangle**(): [`Node`](Node.md) \| [`ImageRectangleNode`](ImageRectangleNode.md)

The rectangular node representing the entire, uncropped bounds of the media (e.g. image, GIFs, or video). The media's position and
rotation can be changed, but it cannot be resized yet via this API. Media types other than images will yield a plain Node object
for now.

#### Returns

[`Node`](Node.md) \| [`ImageRectangleNode`](ImageRectangleNode.md)

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`Node`](Node.md).[`boundsInNode`](Node.md#boundsinnode)

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`Node`](Node.md).[`localPointInNode`](Node.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`removeFromParent`](Node.md#removefromparent)

---

### replaceMedia()

• **replaceMedia**(`media`): `void`

Replace existing media inline. The new media is sized to completely fill the bounds of the existing maskShape; if the
media's aspect ratio differs from the maskShape's, the media will be cropped by the maskShape on either the left/right
or top/bottom edges. Currently only supports images as the new media, but previous media can be of any type.

#### Parameters

• **media**: [`BitmapImage`](../interfaces/BitmapImage.md)

New content to display. Currently must be a [BitmapImage](../interfaces/BitmapImage.md).

#### Returns

`void`

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setPositionInParent`](Node.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setRotationInParent`](Node.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / Node

# Class: Node

A Node represents an object in the scenegraph, the document's visual content tree. Most tangible visual content is a
subclass of Node, but note that some abstract top-level structural nodes (such as PageNode) only extend the more
minimal VisualNode or BaseNode. As a general rule, if you can click or drag an object with the select/move
tool in the UI, then it extends from Node.

A Node’s parent is always a VisualContentNode but may not be another Node (e.g. if the parent is an ArtboardNode)

## Extends

-   [`VisualNode`](VisualNode.md)

## Extended by

-   [`GridLayoutNode`](GridLayoutNode.md)
-   [`GroupNode`](GroupNode.md)
-   [`ImageRectangleNode`](ImageRectangleNode.md)
-   [`MediaContainerNode`](MediaContainerNode.md)
-   [`SolidColorShapeNode`](SolidColorShapeNode.md)
-   [`StrokableNode`](StrokableNode.md)
-   [`TextNode`](TextNode.md)
-   [`UnknownNode`](UnknownNode.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`VisualNode`](VisualNode.md).[`localPointInNode`](VisualNode.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`VisualNode`](VisualNode.md).[`removeFromParent`](VisualNode.md#removefromparent)

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / PageList

# Class: PageList

PageList represents an ordered list of PageNodes, all of which are children of the root node of the document's "scenegraph"
artwork tree (see [ExpressRootNode](ExpressRootNode.md)). A page contains one or more artboards, representing "scenes" in a linear timeline
sequence. Those artboards, in turn, contain all the visual content of the document.

PageList also provides APIs for adding/removing pages from the document. PageList is never empty: it is illegal to
remove the last remaining page from the list.

## Extends

-   [`RestrictedItemList`](RestrictedItemList.md)<[`PageNode`](PageNode.md)\>

## Accessors

### first

• `get` **first**(): `undefined` \| `T`

First item in this list, or undefined if list is empty.

#### Returns

`undefined` \| `T`

---

### last

• `get` **last**(): `undefined` \| `T`

Last item in this list, or undefined if list is empty.

#### Returns

`undefined` \| `T`

---

### length

• `get` **length**(): `number`

Number of items in this list.

#### Returns

`number`

## Methods

### `[iterator]`()

• **\[iterator\]**(): `Iterator`<[`PageNode`](PageNode.md), `any`, `any`\>

Iterates over all the items in this list. Mutations that occur mid-iteration are not reflected by the iterator.

#### Returns

`Iterator`<[`PageNode`](PageNode.md), `any`, `any`\>

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`[iterator]`](RestrictedItemList.md#iterator)

---

### addPage()

• **addPage**(`inputGeometry`): [`PageNode`](PageNode.md)

Create a new page containing a single empty artboard, and add it to the end of the list. The artboard is configured
with the same defaults as in [ArtboardList.addArtboard](ArtboardList.md#addartboard). The page's artboard becomes the default target for
newly inserted content ([Context.insertionParent](Context.md#insertionparent)) and the viewport switches to display this artboard.

#### Parameters

• **inputGeometry**: [`RectangleGeometry`](../interfaces/RectangleGeometry.md)

#### Returns

[`PageNode`](PageNode.md)

---

### indexOf()

• **indexOf**(`item`): `number`

Get index of item in list.

#### Parameters

• **item**: [`PageNode`](PageNode.md)

#### Returns

`number`

index number, or -1 if item isn't in this list.

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`indexOf`](RestrictedItemList.md#indexof)

---

### item()

• **item**(`index`): `undefined` \| [`PageNode`](PageNode.md)

Returns item at the given index, or undefined if index is out of range.

#### Parameters

• **index**: `number`

Zero-based index

#### Returns

`undefined` \| [`PageNode`](PageNode.md)

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`item`](RestrictedItemList.md#item)

---

### moveAfter()

• **moveAfter**(`item`, `after`): `void`

Move `item` so it is immediately after `after` in this list: places `item` at the index one higher than `after`.
Depending on the position in the list `item` originally occupied, some other items in the list may shift to higher
or lower indices as a result. No-op if both arguments are the same item.

#### Parameters

• **item**: [`PageNode`](PageNode.md)

• **after**: [`PageNode`](PageNode.md)

#### Returns

`void`

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`moveAfter`](RestrictedItemList.md#moveafter)

#### Throws

An error if either argument is not contained in this list.

---

### moveBefore()

• **moveBefore**(`item`, `before`): `void`

Move `item` so it is immediately before `before` in this list: places `item` at the index that `before` used
to occupy. Depending on the position in the list `item` originally occupied, some other items in the list may
shift to higher or lower indices as a result. No-op if both arguments are the same item.

#### Parameters

• **item**: [`PageNode`](PageNode.md)

• **before**: [`PageNode`](PageNode.md)

#### Returns

`void`

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`moveBefore`](RestrictedItemList.md#movebefore)

#### Throws

An error if either argument is not contained in this list.

---

### remove()

• **remove**(...`items`): `void`

Remove the items from the list. The items need not be contiguous.

#### Parameters

• ...**items**: [`PageNode`](PageNode.md)[]

#### Returns

`void`

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`remove`](RestrictedItemList.md#remove)

#### Throws

If any of the items are not in the list, or if it is illegal to remove any of the items from this parent.

---

### toArray()

• **toArray**(): readonly [`PageNode`](PageNode.md)[]

All items in the list, as a static array. Mutations that occur later are not reflected in an array returned earlier.

#### Returns

readonly [`PageNode`](PageNode.md)[]

#### Inherited from

[`RestrictedItemList`](RestrictedItemList.md).[`toArray`](RestrictedItemList.md#toarray)
[@express-document-sdk](../overview.md) / PageNode

# Class: PageNode

A PageNode represents a page in the document, a child of the root node of the document's "scenegraph" artwork tree
(see [ExpressRootNode](ExpressRootNode.md)). A page contains one or more artboards, representing "scenes" in a linear timeline
sequence. Those artboards, in turn, contain all the visual content of the document.

To create new pages, see [PageList.addPage](PageList.md#addpage).

## Extends

-   [`BaseNode`](BaseNode.md)

## Implements

-   `Readonly`<[`IRectangularNode`](../interfaces/IRectangularNode.md)\>

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`BaseNode`](BaseNode.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

Although BaseNode's allChildren may yield other BaseNodes, the subclasses Node and ArtboardNode override allChildren
to guarantee all their children are full-fledged Node instances.

#### Returns

`Readonly`<`Iterable`<[`BaseNode`](BaseNode.md), `any`, `any`\>\>

---

### artboards

• `get` **artboards**(): [`ArtboardList`](ArtboardList.md)

The artboards or "scenes" of a page, ordered by timeline sequence.
To create new artboards, see [ArtboardList.addArtboard](ArtboardList.md#addartboard).

#### Returns

[`ArtboardList`](ArtboardList.md)

---

### height

• `get` **height**(): `number`

The height of the node.
All Artboards within a page share the same dimensions.

#### Returns

`number`

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### name

• `get` **name**(): `undefined` \| `string`

The page's name. Displayed as a user-editable label above the current artboard in the UI.

• `set` **name**(`name`): `void`

#### Parameters

• **name**: `undefined` \| `string`

#### Returns

`undefined` \| `string`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### width

• `get` **width**(): `number`

The width of the node.
All Artboards within a page share the same dimensions.

#### Returns

`number`

## Methods

### cloneInPlace()

• **cloneInPlace**(): [`PageNode`](PageNode.md)

Clones this page, all artboards within it, and all content within those artboards. The cloned page is the same size
as the original. Adds the new page immediately after this one in the pages list. The first artboard in the cloned
page becomes the default target for newly inserted content ([Context.insertionParent](Context.md#insertionparent)) and the viewport
switches to display this artboard.

#### Returns

[`PageNode`](PageNode.md)

the cloned page.

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`BaseNode`](BaseNode.md).[`removeFromParent`](BaseNode.md#removefromparent)
[@express-document-sdk](../overview.md) / PathNode

# Class: PathNode

A PathNode represents a generic vector path shape in the scenegraph. Paths cannot be edited through this API
yet, only read.

To create new paths, see [Editor.createPath](Editor.md#createpath).

## Extends

-   [`FillableNode`](FillableNode.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### fill

• `get` **fill**(): `undefined` \| `Readonly`<[`Fill`](../interfaces/Fill.md)\>

• `set` **fill**(`fill`): `void`

The fill applied to the shape, if any.

#### Parameters

• **fill**: `undefined` \| [`Fill`](../interfaces/Fill.md)

#### Returns

`undefined` \| `Readonly`<[`Fill`](../interfaces/Fill.md)\>

---

### fillRule

• `get` **fillRule**(): [`FillRule`](../enumerations/FillRule.md)

The fill rule specifies how the interior area of a path is determined in cases where the path is self-intersecting or
has multiple disjoint parts. The default value is nonZero.

• `set` **fillRule**(`rule`): `void`

#### Parameters

• **rule**: [`FillRule`](../enumerations/FillRule.md)

#### Returns

[`FillRule`](../enumerations/FillRule.md)

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### path

• `get` **path**(): `string`

The path definition as an SVG string. The path data is read-only and cannot be modified via this API yet.
Note that the path data will be normalized, and therefore the `path` getter may return a different SVG string from the path creation input.
For example, "M 10 80 Q 52.5 10, 95 80 T 180 80" becomes "M 10 80 C 38.33 33.33 66.67 33.33 95 80...".

#### Returns

`string`

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### stroke

• `get` **stroke**(): `undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

• `set` **stroke**(`stroke`): `void`

The stroke applied to the shape, if any.
Only [SolidColorStroke](../interfaces/SolidColorStroke.md) values are supported by the setter, but the "type" field is optional
for backward compatibility. Throws if another type is provided.

#### Parameters

• **stroke**: `undefined` \| [`SolidColorStrokeWithOptionalType`](../type-aliases/SolidColorStrokeWithOptionalType.md)

#### Returns

`undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`FillableNode`](FillableNode.md).[`boundsInNode`](FillableNode.md#boundsinnode)

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`FillableNode`](FillableNode.md).[`localPointInNode`](FillableNode.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`FillableNode`](FillableNode.md).[`removeFromParent`](FillableNode.md#removefromparent)

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`FillableNode`](FillableNode.md).[`setPositionInParent`](FillableNode.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`FillableNode`](FillableNode.md).[`setRotationInParent`](FillableNode.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / ReadOnlyItemList

# Class: ReadOnlyItemList<T\>

ReadOnlyItemList represents an ordered list of API objects, representing items that are all children of the
same parent node. (The reverse is not necessarily true, however: this list might not include all
children that exist in the parent node. See [Node.allChildren](Node.md#allchildren) for details).

Items in a bare ReadOnlyItemList cannot be added, removed, or reordered. Subclasses like ItemList may add these capabilities, however.

## Extended by

-   [`RestrictedItemList`](RestrictedItemList.md)

## Type parameters

• **T** _extends_ [`ListItem`](../interfaces/ListItem.md)

## Accessors

### first

• `get` **first**(): `undefined` \| `T`

First item in this list, or undefined if list is empty.

#### Returns

`undefined` \| `T`

---

### last

• `get` **last**(): `undefined` \| `T`

Last item in this list, or undefined if list is empty.

#### Returns

`undefined` \| `T`

---

### length

• `get` **length**(): `number`

Number of items in this list.

#### Returns

`number`

## Methods

### `[iterator]`()

• **\[iterator\]**(): `Iterator`<`T`, `any`, `any`\>

Iterates over all the items in this list. Mutations that occur mid-iteration are not reflected by the iterator.

#### Returns

`Iterator`<`T`, `any`, `any`\>

---

### indexOf()

• **indexOf**(`item`): `number`

Get index of item in list.

#### Parameters

• **item**: `T`

#### Returns

`number`

index number, or -1 if item isn't in this list.

---

### item()

• **item**(`index`): `undefined` \| `T`

Returns item at the given index, or undefined if index is out of range.

#### Parameters

• **index**: `number`

Zero-based index

#### Returns

`undefined` \| `T`

---

### toArray()

• **toArray**(): readonly `T`[]

All items in the list, as a static array. Mutations that occur later are not reflected in an array returned earlier.

#### Returns

readonly `T`[]
[@express-document-sdk](../overview.md) / RectangleNode

# Class: RectangleNode

A RectangleNode represents a rectangle shape in the scenegraph.

To create a new rectangle, see [Editor.createRectangle](Editor.md#createrectangle).

## Extends

-   [`FillableNode`](FillableNode.md)

## Implements

-   [`IRectangularNode`](../interfaces/IRectangularNode.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### bottomLeftRadius

• `get` **bottomLeftRadius**(): `number`

The radius of the bottom left corner, or 0 if the corner is not rounded.

#### Remarks

The actual corner radius that is rendered is capped based on the size of the rectangle
even if the radius value set here is higher.

• `set` **bottomLeftRadius**(`value`): `void`

#### Parameters

• **value**: `number`

#### Returns

`number`

---

### bottomRightRadius

• `get` **bottomRightRadius**(): `number`

The radius of the bottom right corner, or 0 if the corner is not rounded.

#### Remarks

The actual corner radius that is rendered is capped based on the size of the rectangle
even if the radius value set here is higher.

• `set` **bottomRightRadius**(`value`): `void`

#### Parameters

• **value**: `number`

#### Returns

`number`

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### fill

• `get` **fill**(): `undefined` \| `Readonly`<[`Fill`](../interfaces/Fill.md)\>

• `set` **fill**(`fill`): `void`

The fill applied to the shape, if any.

#### Parameters

• **fill**: `undefined` \| [`Fill`](../interfaces/Fill.md)

#### Returns

`undefined` \| `Readonly`<[`Fill`](../interfaces/Fill.md)\>

---

### height

• `get` **height**(): `number`

The height of the node.
Must be at least MIN_DIMENSION.

• `set` **height**(`value`): `void`

#### Parameters

• **value**: `number`

#### Returns

`number`

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### stroke

• `get` **stroke**(): `undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

• `set` **stroke**(`stroke`): `void`

The stroke applied to the shape, if any.
Only [SolidColorStroke](../interfaces/SolidColorStroke.md) values are supported by the setter, but the "type" field is optional
for backward compatibility. Throws if another type is provided.

#### Parameters

• **stroke**: `undefined` \| [`SolidColorStrokeWithOptionalType`](../type-aliases/SolidColorStrokeWithOptionalType.md)

#### Returns

`undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### topLeftRadius

• `get` **topLeftRadius**(): `number`

The radius of the top left corner, or 0 if the corner is not rounded.

#### Remarks

The actual corner radius that is rendered is capped based on the size of the rectangle
even if the radius value set here is higher.

• `set` **topLeftRadius**(`value`): `void`

#### Parameters

• **value**: `number`

#### Returns

`number`

---

### topRightRadius

• `get` **topRightRadius**(): `number`

The radius of the top right corner, or 0 if the corner is not rounded.

#### Remarks

The actual corner radius that is rendered is capped based on the size of the rectangle
even if the radius value set here is higher.

• `set` **topRightRadius**(`value`): `void`

#### Parameters

• **value**: `number`

#### Returns

`number`

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

---

### width

• `get` **width**(): `number`

The width of the node.
Must be at least MIN_DIMENSION.

• `set` **width**(`value`): `void`

#### Parameters

• **value**: `number`

#### Returns

`number`

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`FillableNode`](FillableNode.md).[`boundsInNode`](FillableNode.md#boundsinnode)

---

### getUniformCornerRadius()

• **getUniformCornerRadius**(): `undefined` \| `number`

If all corners have the same rounding radius value, returns that value (or 0 if all corners are not rounded).
If the corner radii differ, returns undefined.

#### Returns

`undefined` \| `number`

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`FillableNode`](FillableNode.md).[`localPointInNode`](FillableNode.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`FillableNode`](FillableNode.md).[`removeFromParent`](FillableNode.md#removefromparent)

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`FillableNode`](FillableNode.md).[`setPositionInParent`](FillableNode.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`FillableNode`](FillableNode.md).[`setRotationInParent`](FillableNode.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```

---

### setUniformCornerRadius()

• **setUniformCornerRadius**(`radius`): `void`

Set all corner radii to the same value. Set to 0 to make the corners non-rounded.

#### Parameters

• **radius**: `number`

#### Returns

`void`

#### Remarks

The actual corner radius that is rendered is capped based on the size of the rectangle
even if the radius value set here is higher.
[@express-document-sdk](../overview.md) / RestrictedItemList

# Class: RestrictedItemList<T\>

Base for ItemLists that have restricted behavior on how items are added to the list,
but allow items to be removed and reordered. Subclasses like ItemList may add more
capabilities, however.

## Extends

-   [`ReadOnlyItemList`](ReadOnlyItemList.md)<`T`\>

## Extended by

-   [`ArtboardList`](ArtboardList.md)
-   [`ItemList`](ItemList.md)
-   [`PageList`](PageList.md)

## Type parameters

• **T** _extends_ [`ListItem`](../interfaces/ListItem.md)

## Accessors

### first

• `get` **first**(): `undefined` \| `T`

First item in this list, or undefined if list is empty.

#### Returns

`undefined` \| `T`

---

### last

• `get` **last**(): `undefined` \| `T`

Last item in this list, or undefined if list is empty.

#### Returns

`undefined` \| `T`

---

### length

• `get` **length**(): `number`

Number of items in this list.

#### Returns

`number`

## Methods

### `[iterator]`()

• **\[iterator\]**(): `Iterator`<`T`, `any`, `any`\>

Iterates over all the items in this list. Mutations that occur mid-iteration are not reflected by the iterator.

#### Returns

`Iterator`<`T`, `any`, `any`\>

#### Inherited from

[`ReadOnlyItemList`](ReadOnlyItemList.md).[`[iterator]`](ReadOnlyItemList.md#iterator)

---

### indexOf()

• **indexOf**(`item`): `number`

Get index of item in list.

#### Parameters

• **item**: `T`

#### Returns

`number`

index number, or -1 if item isn't in this list.

#### Inherited from

[`ReadOnlyItemList`](ReadOnlyItemList.md).[`indexOf`](ReadOnlyItemList.md#indexof)

---

### item()

• **item**(`index`): `undefined` \| `T`

Returns item at the given index, or undefined if index is out of range.

#### Parameters

• **index**: `number`

Zero-based index

#### Returns

`undefined` \| `T`

#### Inherited from

[`ReadOnlyItemList`](ReadOnlyItemList.md).[`item`](ReadOnlyItemList.md#item)

---

### moveAfter()

• **moveAfter**(`item`, `after`): `void`

Move `item` so it is immediately after `after` in this list: places `item` at the index one higher than `after`.
Depending on the position in the list `item` originally occupied, some other items in the list may shift to higher
or lower indices as a result. No-op if both arguments are the same item.

#### Parameters

• **item**: `T`

• **after**: `T`

#### Returns

`void`

#### Throws

An error if either argument is not contained in this list.

---

### moveBefore()

• **moveBefore**(`item`, `before`): `void`

Move `item` so it is immediately before `before` in this list: places `item` at the index that `before` used
to occupy. Depending on the position in the list `item` originally occupied, some other items in the list may
shift to higher or lower indices as a result. No-op if both arguments are the same item.

#### Parameters

• **item**: `T`

• **before**: `T`

#### Returns

`void`

#### Throws

An error if either argument is not contained in this list.

---

### remove()

• **remove**(...`items`): `void`

Remove the items from the list. The items need not be contiguous.

#### Parameters

• ...**items**: `T`[]

#### Returns

`void`

#### Throws

If any of the items are not in the list, or if it is illegal to remove any of the items from this parent.

---

### toArray()

• **toArray**(): readonly `T`[]

All items in the list, as a static array. Mutations that occur later are not reflected in an array returned earlier.

#### Returns

readonly `T`[]

#### Inherited from

[`ReadOnlyItemList`](ReadOnlyItemList.md).[`toArray`](ReadOnlyItemList.md#toarray)
[@express-document-sdk](../overview.md) / SolidColorShapeNode

# Class: SolidColorShapeNode

A SolidColorShapeNode is a prepackaged shape with a single color property that appears as a leaf node in the UI, even if it
is composed of multiple separate paths.

## Extends

-   [`Node`](Node.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### color

• `get` **color**(): `undefined` \| `Readonly`<[`Color`](../interfaces/Color.md)\>

The color of the single color shape.

• `set` **color**(`color`): `void`

#### Parameters

• **color**: `undefined` \| [`Color`](../interfaces/Color.md)

#### Returns

`undefined` \| `Readonly`<[`Color`](../interfaces/Color.md)\>

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`Node`](Node.md).[`boundsInNode`](Node.md#boundsinnode)

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`Node`](Node.md).[`localPointInNode`](Node.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`removeFromParent`](Node.md#removefromparent)

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setPositionInParent`](Node.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setRotationInParent`](Node.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / StrokableNode

# Class: StrokableNode

Base class for a Node that can have its own stroke.

## Extends

-   [`Node`](Node.md)

## Extended by

-   [`FillableNode`](FillableNode.md)
-   [`LineNode`](LineNode.md)
-   [`StrokeShapeNode`](StrokeShapeNode.md)

## Implements

-   [`IStrokableNode`](../interfaces/IStrokableNode.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### stroke

• `get` **stroke**(): `undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

• `set` **stroke**(`stroke`): `void`

The stroke applied to the shape, if any.
Only [SolidColorStroke](../interfaces/SolidColorStroke.md) values are supported by the setter, but the "type" field is optional
for backward compatibility. Throws if another type is provided.

#### Parameters

• **stroke**: `undefined` \| [`SolidColorStrokeWithOptionalType`](../type-aliases/SolidColorStrokeWithOptionalType.md)

#### Returns

`undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`Node`](Node.md).[`boundsInNode`](Node.md#boundsinnode)

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`Node`](Node.md).[`localPointInNode`](Node.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`removeFromParent`](Node.md#removefromparent)

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setPositionInParent`](Node.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setRotationInParent`](Node.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / StrokeShapeNode

# Class: StrokeShapeNode

A StrokeShapeNode is prepackaged shape that has a single stroke property and appears as a leaf node in the UI, even
if it is composed of multiple separate paths.

## Extends

-   [`StrokableNode`](StrokableNode.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### stroke

• `get` **stroke**(): `undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

• `set` **stroke**(`stroke`): `void`

The stroke applied to the shape, if any.
Only [SolidColorStroke](../interfaces/SolidColorStroke.md) values are supported by the setter, but the "type" field is optional
for backward compatibility. Throws if another type is provided.

#### Parameters

• **stroke**: `undefined` \| [`SolidColorStrokeWithOptionalType`](../type-aliases/SolidColorStrokeWithOptionalType.md)

#### Returns

`undefined` \| `Readonly`<[`Stroke`](../interfaces/Stroke.md)\>

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`StrokableNode`](StrokableNode.md).[`boundsInNode`](StrokableNode.md#boundsinnode)

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`StrokableNode`](StrokableNode.md).[`localPointInNode`](StrokableNode.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`StrokableNode`](StrokableNode.md).[`removeFromParent`](StrokableNode.md#removefromparent)

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`StrokableNode`](StrokableNode.md).[`setPositionInParent`](StrokableNode.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`StrokableNode`](StrokableNode.md).[`setRotationInParent`](StrokableNode.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / TextContentModel

# Class: TextContentModel

Represents a complete piece of text content flow, which may be split across multiple [TextNode](TextNode.md) frames for display.
Use this model to get or modify the text string and the style ranges applied to it.

## Accessors

### allTextNodes

• `get` **allTextNodes**(): `Readonly`<`Iterable`<[`TextNode`](TextNode.md), `any`, `any`\>\>

Get ordered list of all [TextNode](TextNode.md)s that display this text content in the scenegraph. The text content
starts in the first  [TextNode](TextNode.md) "frame", and then flows into the second node once it has filled the first one. The ending of the
text content may not be visible at all, if the last [TextNode](TextNode.md) "frame" is not large enough to accommodate it.

If there are multiple [TextNode](TextNode.md)s, all of them must be configured to use [AreaTextLayout](../interfaces/AreaTextLayout.md).

#### Returns

`Readonly`<`Iterable`<[`TextNode`](TextNode.md), `any`, `any`\>\>

---

### characterStyleRanges

• `get` **characterStyleRanges**(): readonly [`CharacterStylesRange`](../interfaces/CharacterStylesRange.md)[]

The character styles are applied to different ranges of this text content. When setting character styles, any style
properties that are not provided are reset to their defaults (contrast to [applyCharacterStyles](TextContentModel.md#applycharacterstyles) which
preserves the text's existing styles for any fields not specified). When *getting* styles, all fields are always
provided.

Note: existing fonts used in the document, returned by this getter, are not guaranteed to be ones the current user
has rights to edit with. The *setter* only accepts the AvailableFont type which has been verified to be usable.

• `set` **characterStyleRanges**(`styles`): `void`

#### Parameters

• **styles**: readonly [`CharacterStylesRangeInput`](../interfaces/CharacterStylesRangeInput.md)[]

#### Returns

readonly [`CharacterStylesRange`](../interfaces/CharacterStylesRange.md)[]

---

### id

• `get` **id**(): `string`

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

To determine if two TextNodes are connected to the same TextContentModel,
check if both models have the same id.
Comparing two models using `===` will always fail.

#### Returns

`string`

---

### paragraphStyleRanges

• `get` **paragraphStyleRanges**(): readonly [`ParagraphStylesRange`](../interfaces/ParagraphStylesRange.md)[]

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

The styles applied to different paragraphs of this text content.

• `set` **paragraphStyleRanges**(`styles`): `void`

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

Apply styles to different paragraphs of this text content. Any style properties that are not provided are reset to their defaults.
When **getting** styles, all properties are always provided.

Paragraphs are separated by newline characters (`\n`). The ranges specified here should align with
those boundaries. If multiple ranges provided overlap a single paragraph, the first one to overlap is applied to the
entire paragraph.

#### Throws

if the text content contains fonts unavailable to the current user and an ordered-list style is being applied.

#### Parameters

• **styles**: readonly [`ParagraphStylesRangeInput`](../interfaces/ParagraphStylesRangeInput.md)[]

#### Returns

readonly [`ParagraphStylesRange`](../interfaces/ParagraphStylesRange.md)[]

---

### text

• `get` **text**(): `string`

The complete text string, which may span multiple [TextNode](TextNode.md) "frames" in the scenegraph.

• `set` **text**(`textContent`): `void`

#### Parameters

• **textContent**: `string`

#### Returns

`string`

## Methods

### applyCharacterStyles()

• **applyCharacterStyles**(`styles`, `range`?): `void`

Apply one or more styles to the characters in the given range, leaving any style properties that were not specified
unchanged. Does not modify any styles in the text outside this range. Contrast to the [characterStyleRanges](TextContentModel.md#characterstyleranges)
setter, which specifies new style range(s) for the entire text at once, and resets any unspecified properties back to
default styles.

#### Parameters

• **styles**: [`CharacterStylesInput`](../interfaces/CharacterStylesInput.md)

The styles to apply.

• **range?**: [`TextRange`](../interfaces/TextRange.md)

The start and length of the character sequence to which the styles should be applied.
The styles will be applied to the entire text content flow if not specified.
If the specified range doesn't align well with the paragraph boundaries, the range will be expanded to cover the
entire paragraphs, it overlaps.

#### Returns

`void`

---

### applyParagraphStyles()

• **applyParagraphStyles**(`styles`, `range`?): `void`

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

Apply one or more styles to the paragraphs in the given range, leaving any style properties that were not specified
unchanged. Does not modify any styles in the text outside this range. Contrast to the [paragraphStyleRanges](TextContentModel.md#paragraphstyleranges)
setter, which specifies new style range(s) for the entire text at once, and resets any unspecified properties back to
default styles.

#### Parameters

• **styles**: [`ParagraphStylesInput`](../interfaces/ParagraphStylesInput.md)

The styles to apply.

• **range?**: [`TextRange`](../interfaces/TextRange.md)

The start and length of character sequence to which the styles should be applied.
If not specified the styles will be applied to the entire piece of text content flow.

#### Returns

`void`

---

### hasUnavailableFonts()

• **hasUnavailableFonts**(): `boolean`

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

Returns true if this text contains any fonts unavailable to the current user.
Currently, if any unavailable fonts are present, the text content cannot be modified and
certain styling changes are limited as well. To remove these restrictions, you must modify
the character styles to use only AvailableFonts.

#### Returns

`boolean`
[@express-document-sdk](../overview.md) / TextNode

# Class: TextNode

A TextNode represents a text display frame in the scenegraph. It may display an entire piece of text, or sometimes just
a subset of longer text that flows across multiple TextNode "frames". Because of this, the TextNode does not directly hold
the text content and styles – instead it refers to a [TextContentModel](TextContentModel.md), which may be shared across multiple TextNode frames.

To create new a single-frame piece of text, see [Editor.createText](Editor.md#createtext). APIs are not yet available to create
multi-frame text flows.

## Extends

-   [`Node`](Node.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

Note: The center of the orphaned TextNode may be different from the center of the node placed on a page. It is
recommended to use this property only when the node is placed on a page.

---

### fullContent

• `get` **fullContent**(): [`TextContentModel`](TextContentModel.md)

The model containing the complete text string and its styles, only part of which may be visible within the bounds of
this specific TextNode "frame." The full text content flow may be split across multiple frames, and/or it may be clipped if a
fixed-size frame using [AreaTextLayout](../interfaces/AreaTextLayout.md) does not fit all the (remaining) text.

Note: When traversing the scenegraph in search of text content, bear in mind that multiple TextNodes may refer to the
same single [TextContentModel](TextContentModel.md); this can give the impression that the same text is duplicated multiple times when it is
not. Use [TextContentModel](TextContentModel.md).id to determine whether a given piece of text content is unique or if it's already been
encountered before.

#### Returns

[`TextContentModel`](TextContentModel.md)

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### layout

• `get` **layout**(): `Readonly`<[`PointTextLayout`](../interfaces/PointTextLayout.md) \| [`AutoHeightTextLayout`](../interfaces/AutoHeightTextLayout.md) \| [`AreaTextLayout`](../interfaces/AreaTextLayout.md) \| [`UnsupportedTextLayout`](../interfaces/UnsupportedTextLayout.md)\>

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

• `set` **layout**(`layout`): `void`

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

Sets the layout mode of the TextNode "frame."

If this TextNode is part of a multi-frame text content flow, it must be configured to use [AreaTextLayout](../interfaces/AreaTextLayout.md). Other
layout modes, except for [AreaTextLayout](../interfaces/AreaTextLayout.md), are only available for single-frame text.

#### Throws

if changing text layout to/from [TextType.magicFit](../enumerations/TextType.md#magicfit) or [TextType.circular](../enumerations/TextType.md#circular) layout when the text contains font(s) unavailable to the current user.

#### Throws

if [TextNode](TextNode.md) is part of a multi-frame text content flow and the layout is not [AreaTextLayout](../interfaces/AreaTextLayout.md).

#### Throws

if [TextNode](TextNode.md) is not a part of a multi-frame text content flow and the layout is [AreaTextLayout](../interfaces/AreaTextLayout.md).

#### Parameters

• **layout**: [`PointTextLayout`](../interfaces/PointTextLayout.md) \| [`AutoHeightTextLayout`](../interfaces/AutoHeightTextLayout.md) \| [`AreaTextLayout`](../interfaces/AreaTextLayout.md)

#### Returns

`Readonly`<[`PointTextLayout`](../interfaces/PointTextLayout.md) \| [`AutoHeightTextLayout`](../interfaces/AutoHeightTextLayout.md) \| [`AreaTextLayout`](../interfaces/AreaTextLayout.md) \| [`UnsupportedTextLayout`](../interfaces/UnsupportedTextLayout.md)\>

The layout mode of the TextNode "frame."

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### nextTextNode

• `get` **nextTextNode**(): `undefined` \| [`TextNode`](TextNode.md)

The next TextNode that text overflowing this node will spill into, if any. If undefined and this TextNode is fixed size
([AreaTextLayout](../interfaces/AreaTextLayout.md)), any text content that does not fit within this node's area will be clipped.

To get *all* TextNodes that the text content may be split across, use `TextNode.fullContent.allTextNodes`.

#### Returns

`undefined` \| [`TextNode`](TextNode.md)

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### text

• `get` **text**(): `string`

The text string content which is partially *or* fully displayed in this TextNode "frame."
WARNING: If a piece of text content flows across several TextNodes, *each* TextNode's `text` getter will return
the *entire* text content string.

#### Deprecated

- Use the text getter on [TextContentModel](TextContentModel.md) instead. Access it via `TextNode.fullContent.text`.

• `set` **text**(`textContent`): `void`

Sets the text content of the TextNode.
WARNING: If a piece of text content flows across several TextNodes,
*each* TextNode's `text` setter will sets the *entire* text content string.

#### Deprecated

- Use the text setter on [TextContentModel](TextContentModel.md) instead. Access it via `TextNode.fullContent.text`.

#### Parameters

• **textContent**: `string`

#### Returns

`string`

---

### textAlignment

• `get` **textAlignment**(): [`TextAlignment`](../enumerations/TextAlignment.md)

The horizontal text alignment of the TextNode. Alignment is always the same across this node's entire text content.

• `set` **textAlignment**(`alignment`): `void`

#### Parameters

• **alignment**: [`TextAlignment`](../enumerations/TextAlignment.md)

#### Returns

[`TextAlignment`](../enumerations/TextAlignment.md)

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

Note: The top-left of the orphaned TextNode may be different from the top-left of the node placed on a
page. It is recommended to use this property only when the node is placed on a page.

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualEffects

• `get` **visualEffects**(): readonly [`VisualEffectType`](../enumerations/VisualEffectType.md)[]

#### Returns

readonly [`VisualEffectType`](../enumerations/VisualEffectType.md)[]

The list of visual effects applied to the TextNode.

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`Node`](Node.md).[`boundsInNode`](Node.md#boundsinnode)

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`Node`](Node.md).[`localPointInNode`](Node.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`removeFromParent`](Node.md#removefromparent)

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setPositionInParent`](Node.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setRotationInParent`](Node.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / UnavailableFont

# Class: UnavailableFont

Font the current user does not have access or licensing permissions to create / edit content with.

## Extends

-   [`BaseFont`](BaseFont.md)

## Accessors

### availableForEditing

• `get` **availableForEditing**(): `false`

Whether the current user has permission to create / edit content using this font.

#### Returns

`false`

---

### family

• `get` **family**(): `string`

The font family containing the font.

#### Returns

`string`

---

### postscriptName

• `get` **postscriptName**(): `string`

The PostScript name of the font.

#### Returns

`string`

---

### style

• `get` **style**(): `string`

The style of the font within the family.

#### Returns

`string`
[@express-document-sdk](../overview.md) / UnknownNode

# Class: UnknownNode

An UnknownNode is a node with limited support and therefore treated as a leaf node.

## Extends

-   [`Node`](Node.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

The children of a Node are always other Node classes (never the more minimal BaseNode).

#### Returns

`Readonly`<`Iterable`<[`Node`](Node.md), `any`, `any`\>\>

---

### blendMode

• `get` **blendMode**(): [`BlendMode`](../enumerations/BlendMode.md)

Blend mode determines how a node is composited onto the content below it. The default value is
[BlendMode.normal](../enumerations/BlendMode.md#normal) for most nodes, and [BlendMode.passThrough](../enumerations/BlendMode.md#passthrough) for GroupNodes.

• `set` **blendMode**(`value`): `void`

#### Parameters

• **value**: [`BlendMode`](../enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../enumerations/BlendMode.md)

---

### boundsInParent

• `get` **boundsInParent**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

An axis-aligned box in the parent’s coordinate space encompassing the node’s layout bounds (its
[boundsLocal](VisualNode.md#boundslocal), as transformed by its position and rotation relative to the parent). If the node has
rotation, the top-left of its boundsLocal box (aligned to its own axes) is not necessarily located at the
top-left of the boundsInParent box (since it's aligned to the parent's axes). This value is well-defined
even for an orphan node with no parent.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### locked

• `get` **locked**(): `boolean`

The node's lock/unlock state. Locked nodes are excluded from the selection (see [Context.selection](Context.md#selection)), and
cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
are permitted. However, please consider if modifying a locked node would align with user expectations
before using the API to make changes to locked nodes.

• `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: `boolean`

#### Returns

`boolean`

---

### opacity

• `get` **opacity**(): `number`

The node's opacity, from 0.0 to 1.0

• `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### rotation

• `get` **rotation**(): `number`

The node's local rotation angle in degrees, relative to its parent's axes. Use `setRotationInParent` to
change rotation by rotating around a defined centerpoint.

#### Returns

`number`

---

### rotationInScreen

• `get` **rotationInScreen**(): `number`

The node's total rotation angle in degrees, relative to the overall global view of the document – including any
cumulative rotation from the node's parent containers.

#### Returns

`number`

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### transformMatrix

• `get` **transformMatrix**(): [`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

The node's transform matrix relative to its parent.

#### Returns

[`mat2d`](https://glmatrix.net/docs/module-mat2d.html)

---

### translation

• `get` **translation**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

The translation of the node along its parent's axes. This is identical to the translation component of
`transformMatrix`. It is often simpler to set a node's position using `setPositionInParent` than by
setting translation directly.

• `set` **translation**(`value`): `void`

#### Parameters

• **value**: [`Point`](../interfaces/Point.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

## Methods

### boundsInNode()

• **boundsInNode**(`targetNode`): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

Convert the node's [boundsLocal](VisualNode.md#boundslocal) to an axis-aligned bounding box in the coordinate space of the target
node. Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree
relative to one another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

#### Inherited from

[`Node`](Node.md).[`boundsInNode`](Node.md#boundsinnode)

---

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

#### Inherited from

[`Node`](Node.md).[`localPointInNode`](Node.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`removeFromParent`](Node.md#removefromparent)

---

### setPositionInParent()

• **setPositionInParent**(`parentPoint`, `localRegistrationPoint`): `void`

Move the node so the given `localRegistrationPoint` in its local coordinates is placed at the given
`parentPoint` in its parent's coordinates (taking into account any rotation on this node, etc.).

#### Parameters

• **parentPoint**: [`Point`](../interfaces/Point.md)

Point in this node's parent's coordinate space to move `localRegistrationPoint` to

• **localRegistrationPoint**: [`Point`](../interfaces/Point.md)

Point in this node's local coordinate space to align with `parentPoint`

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setPositionInParent`](Node.md#setpositioninparent)

#### Example

Center a rectangle within its parent artboard:

```js
rectangle.setPositionInParent(
    { x: artboard.width / 2, y: artboard.height / 2 },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
);
```

---

### setRotationInParent()

• **setRotationInParent**(`angleInDegrees`, `localRotationPoint`): `void`

Set the node’s rotation angle relative to its parent to exactly the given value, keeping the given point in the
node’s local coordinate space at a fixed location within the parent. Disregards any rotation the node may already
have had. The angle set here may not be the absolute rotation angle seen on screen, if the parent or other
ancestors also have rotation of their own.

#### Parameters

• **angleInDegrees**: `number`

Angle in degrees.

• **localRotationPoint**: [`Point`](../interfaces/Point.md)

Point to rotate around, in node's local coordinates.

#### Returns

`void`

#### Inherited from

[`Node`](Node.md).[`setRotationInParent`](Node.md#setrotationinparent)

#### Example

Rotate the rectangle 45 degrees clockwise around its centerpoint:

```js
rectangle.setRotationInParent(45, { x: rectangle.width / 2, y: rectangle.height / 2 });
```
[@express-document-sdk](../overview.md) / Viewport

# Class: Viewport

Represents the area of the canvas that is currently visible on-screen.

## Methods

### bringIntoView()

• **bringIntoView**(`node`): `void`

Adjusts the viewport to make the node's bounds visible on-screen, assuming all bounds are within the artboard bounds.
Makes the node's [ArtboardNode](ArtboardNode.md) or [PageNode](PageNode.md) visible if they were not already visible
(which may result in [Context.selection](Context.md#selection) being cleared). It is strongly recommended
to further draw user's attention to the node, set it as the [Context.selection](Context.md#selection) following this call.

After this call, the value of [Context.insertionParent](Context.md#insertionparent) will always be the node containing [ArtboardNode](ArtboardNode.md).

Note that the node might still not appear visible if:

- Its animation settings make it invisible at the beginning of the [ArtboardNode](ArtboardNode.md) "scene".
- It is obscured underneath other artwork in the z-order.
- It is hidden by a [GroupNode](GroupNode.md)'s mask or similar cropping.

#### Parameters

• **node**: [`VisualNode`](VisualNode.md)

#### Returns

`void`
[@express-document-sdk](../overview.md) / VisualNode

# Class: VisualNode

A "node" represents an object in the scenegraph, the document's visual content tree. This class represents any node
that can be visually perceived in the content. Most visual content is a subclass of the richer Node class which extends
VisualNode with more properties, but the overall ArtboardNode container only supports the VisualNode APIs
(and higher-level more abstract containers like PageNode extend only the minimal BaseNode class).

Some VisualNodes might have a non-visual parent such as a PageNode.

## Extends

-   [`BaseNode`](BaseNode.md)

## Extended by

-   [`ArtboardNode`](ArtboardNode.md)
-   [`ContainerNode`](../interfaces/ContainerNode.md)
-   [`Node`](Node.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](AddOnData.md)

Get [AddOnData](AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`BaseNode`](BaseNode.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](../interfaces/ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
overall display z-order.

Although BaseNode's allChildren may yield other BaseNodes, the subclasses Node and ArtboardNode override allChildren
to guarantee all their children are full-fledged Node instances.

#### Returns

`Readonly`<`Iterable`<[`BaseNode`](BaseNode.md), `any`, `any`\>\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](../interfaces/Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
*not* necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](../interfaces/Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](BaseNode.md)

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](../interfaces/Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](VisualNode.md)

## Methods

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](../interfaces/Point.md)

• **targetNode**: [`VisualNode`](VisualNode.md)

#### Returns

`Readonly`<[`Point`](../interfaces/Point.md)\>

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`BaseNode`](BaseNode.md).[`removeFromParent`](BaseNode.md#removefromparent)
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Document API
  - Express Communication API
  - Document Model Sandbox
  - Adobe Express
  - JavaScript
  - Extensibility
  - API
title: Exploring the Adobe Document API Concepts
description: In this article, you'll learn about the structures that make up the Adobe Express Document Object Model, their features, and how they're reflected in the Reference documentation.
contributors:
  - https://github.com/undavide
---

# Adobe Express Document API Concepts

The structures that make up the Adobe Express Document Object Model, their features, and how they're reflected in the Reference documentation.

## Overview

In this article, you'll dive deep into the architecture and key elements of the Adobe Express Document Object Model (DOM) and why the Reference Documentation is the primary tool to explore it. Understanding the structures at play, hierarchy, and inheritance system will help you develop add-ons that exploit their full potential.

### Getting started with the DOM

The notion of **Document Object Model** (DOM) is key to any scripting environment; developers refer to _scripting_ when their programs use tools primarily available through the application's User Interface (UI) but programmatically, with code. For example, the [Grids tutorial](/guides/tutorials/grids-addon.md) add-on creates a grid system while operating with built-in elements like shapes and editing their dimensions, positions, fills, and blending modes. If you were to implement an unsupported object type, you'd need to go beyond the combination of existing tools—i.e., outside the scripting realm.[^1]

It is essential to hierarchically organize the features that are surfaced[^2] to the scripting layer. For example, a shape is not just contained within a document: it may be included in a particular Group in a certain Artboard, which belongs to a specific Page of a Document. Additionally, Ellipses and Rectangles, as shapes, share some properties, such as the ability to be filled or stroked with a solid color; in that respect, though, they differ from a bitmap image, which can be stroked but not filled.

More formally stated, any scripting environment must expose information about the **Containment Structures** (parent/child relations, like groups nesting shapes) and **Inheritance Hierarchies** (shared attributes like the opacity property available to both) of any element it deals with. Such a collection of organized information is called the Document Object Model, or DOM.

Developers with a front-end background may instinctively associate the notion of DOM with HTML and the Browser. Although it has been the most common case for decades, all applications supporting scripting rely on their own Document Object Model—as those working with desktop versions of the Creative Cloud know very well. The Adobe Express add-on system is technically different from CEP extensions in Adobe After Effects or UXP plugins in Adobe Photoshop; still, the concept of the DOM is equally valid.

<InlineAlert variant="warning" slots="heading, text1, text2, text3w" />

**Warning** <!-- 👈 won't be rendered -->

Some confusion may arise regarding the meaning of the following terms—let me clarify.

- **Document Model Sandbox**: the sandboxed JavaScript environment that makes the Document API available to add-on developers. It's usually juxtaposed with the iframe UI: both reciprocally share APIs via proxy, as described in [this tutorial](/guides/tutorials/stats-addon.md).
- **Document Object Model**: it represents Adobe Express documents' structure, the hierarchies between each element, and their inheritance.

You may think about the Document API as operating in the context of the DOM—while the Document Model Sandbox provides a secure and isolated environment for such code to run.

### Coding along

You are encouraged to try the code snippets discussed here; please use [this boilerplate](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/express-dimensions-addon) to follow along. It contains a demo add-on in two states: the complete version (in the `express-dimensions-end` folder, whose code is also found in the [Final Project](#final-project) section at the bottom of this page) and a starting point (`express-dimensions-start`) that you can also use to test your assumptions and inspect the Console. The Document API code belongs to the `src/documentSandbox/code.js` file.

```js
// ...
import { editor, colorUtils } from "express-document-sdk";
function start() {
  runtime.exposeApi({
    log: () => {
      const selectedNode = editor.context.selection[0];
      console.log("Currently selected node", selectedNode);
    },
    // ...
  });
}
```

Run the add-on, select any object in the UI, and click the "Log selected node" button: it'll be logged in the Console.

![](images/refs-addon-log.png)

## The Adobe Express DOM

An Adobe Express document is internally represented as a hierarchical tree of **nodes**. Some of them may branch: in other words, contain other nodes, host children—like an Artboard or a Group with some shapes or media in them. Other ones are so-called leaf nodes: the tree's endpoints, for example, a text or a line.

![](images/refs-addon-scenegraph.png)

Such a structure is referred to as the **Scenegraph**, and it allows for efficient rendering, manipulation, and traversal of all scene elements.

### Object-Oriented programming concepts

Understanding the hierarchical tree of nodes in the Adobe Express DOM requires a firm grasp of a handful of key concepts in object-oriented programming (OOP).

- **Classes**: the blueprint for creating objects. They define a set of properties and methods the created objects (known as _instances_ of that class) will have. For example, when users add a page to an Adobe Express document, a new `PageNode` class is _instantiated_. Such a Page instance comes by default with a peculiar set of accessors (properties) like `width`, `height`, and `artboards` and methods like `removeFromParent()`.
- **Inheritance**: classes can inherit properties and methods from an existing class. The `LineNode` inherits from the `StrokableNode`, which in turn inherits from the `Node` class, establishing a parent/child relation.
- **Class Extension**: this concept is closely related to Inheritance. A child class inherits the methods and properties from its parent and extends them with its additional ones. `TextNode` extends `Node`, adding, among others, the `text` property and the `setPositionInParent()` method.
- **Interfaces**: define a _contract_ for classes without implementing any behavior themselves. They specify a set of methods and properties a class must have but do not define how they work internally. For example, the `ContainerNode` interface mandates the implementation of `allChildren`, `children`, `parent`, and `type` properties. Classes implementing this interface, such as `ArtboardNode` and `GroupNode`, are responsible for providing these properties' actual implementation. By doing so, these classes conform to the structure and requirements defined by the `ContainerNode` interface. Interfaces can be extended, too: the `ColorFill` inherits the `type` property from the `Fill` interface and extends it with an additional `color`.

Compared to other Adobe desktop applications, the Adobe Express DOM features a remarkably clean class hierarchy, where every element has a well-defined lineage that traces back to a minimal set of root classes.

![](images/refs-addon-hierarchy.png)

### How to read the Reference

With this knowledge, you can use the [Document APIs](/references/document-sandbox/document-apis/) reference as the primary tool to study and learn about the Adobe Express DOM.

![](images/refs-addon-doc.png)

There is a comprehensive list of Classes (_blueprints_), Interfaces (_contracts_), and Constants in the left navigation bar. Familiarize yourself with this content and learn how to read it.

Using the `EllipseNode` as an example, you can find:

- The **class name**, always PascalCase.
- A short **description** of what it represents and its role in the scenegraph.
- The **inheritance tree**: in this case, `EllipseNode` is a subclass of `FillableNode`; following the chain, you'll find that, in turn, this inherits from `StrokableNode`, which eventually comes from the `Node` root class.
- A list of **accessors** (properties), like `stroke`, `opacity`, etc.
- A list of **methods**, like `removeFromParent()` and `setPositionInParent()`.

![](images/refs-addon-ref.png)

Some accessors are read-only, for instance, parent or rotation; some have **getters** and **setters**, like `locked` or `fill`. Properties can support a range of value kinds, from primitive values to objects, class instances, or collections. Let's break down the `translation` property as an example.

![](images/refs-addon-accessor.png)

It's split into two parts: `get` (the getter, when you read the property) and `set` (the setter, when you write it). From the description, you see that it's a way to find out about the node's coordinates relative to its parent. The return type for the getter (wrapped with `< >` angle brackets) is `{ x: number, y: number}`, i.e. an object with numeric `x` and `y` properties. You also read that this property is inherited from the `FillableNode` class that `EllipseNode` extends. The setter expects a `value`, which the Parameters table describes as of type `Object`, with the same numeric `x` and `y` properties; it returns `void` (i.e., nothing). Given all this, it's possible to confidently write something along these lines.

```js
const ellipse = editor.createEllipse();
editor.context.insertionParent.children.append(ellipse); // attach to the scenegraph
console.log(ellipse.translation); // { x: 0, y: 0 }
ellipse.translation = { x: 100, y: 50 };
```

Some properties rely on interfaces to define their type. The ellipse's `stroke` happens to be of type `Stroke`, an interface whose _contract_ mandates the implementation of five different properties: `color`, `width`, `position`, `dashPattern`, and `dashOffset`.

![](images/refs-addon-stroke.png)

### The importance of Constants

Let's use the `stroke` to demonstrate the use of Constants in the DOM. They are a named import—mind the lowercase spelling.

```js
import { editor, colorUtils, constants } from "express-document-sdk";
```

They represent a safe, user-friendly way to refer to internal values (subject to change) that developers should not directly manipulate. For example, the stroke's `position` property is of type `StrokePosition`, which happens to be enumerable—a fixed set of pre-defined values.

![](images/refs-addon-strokeposition.png)

Internally, the center, inside, and outside positions are represented with the integers `0`, `1`, and `2`. You should instead use the `StrokePosition` constant and its available members:

- `StrokePosition.center`
- `StrokePosition.inside`
- `StrokePosition.outside`

Using constants will ensure expected outcomes, in case Adobe Express engineers remap values in the future. This is the code needed to conclude the `stroke` example.

```js
const ellipse = editor.createEllipse();
editor.context.insertionParent.children.append(ellipse);
ellipse.stroke = {
  color: { red: 0.7, green: 0.6, blue: 1, alpha: 1 },
  dashOffset: 0,
  dashPattern: [4, 2],
  // position: 1 ❌
  position: constants.StrokePosition.inside, // ✅
  width: 3,
};
```

The [Document Stats tutorial](/guides/tutorials/stats-addon.md) features an add-on that goes through all elements in the scenegraph and groups them by `type`, providing a count of each: `ComplexShape`, `Group`, etc.

![](images/stats-addon-animation.gif)

To log the `type` property is acceptable in this specific case, although the proper way to check against node types involves constants; the `type` itself is an internal string value mapped to the `SceneNodeType` enumerable.

```js
❌ if (someNode.type === "ab:Artboard") { /* ... */ }
✅ if (someNode.type === constants.SceneNodeType.artboard) { /* ... */ }
```

### Helper functions

Let's return to strokes and fills: they are expressed as plain objects; in fact, all the properties the `Stroke` interface requires, like `dashPattern`, were previously provided. The `editor.makeStroke()` utility will fill in the default values when you don't provide them.

```js
const ellipse = editor.createEllipse();
editor.context.insertionParent.children.append(ellipse);
ellipse.stroke = editor.makeStroke({
  color: { red: 0.7, green: 0.6, blue: 1, alpha: 1 },
});
```

Here, you get a 1-pixel, solid stroke of the provided color, the only property you've explicitly supplied. There's a similar helper function for the `ColorFill` interface.

```js
ellipse.fill = editor.makeColorFill({
  red: 0.6,
  green: 0.9,
  blue: 0.6,
  alpha: 1,
});
```

If you wonder where all the help is since you've to type the entire color object manually anyway, let me remind you that the `fill` property is of type `ColorFill`: such an interface expects a `color` property (the one provided above) as well as a `type` expressed by the `FillType.color` constants. Without the `makeColorFill()` method, you must write the following.

```js
ellipse.fill = {
  color: { red: 0.6, green: 0.9, blue: 0.6, alpha: 1 },
  type: constants.FillType.color, // 👈
};
```

<InlineAlert variant="info" slots="text1, text2" />

A specific **naming convention** exists for methods used in the Adobe Express DOM.

- `make*`: used for plain objects and helper utilities, e.g.,`makeColorFill()`.
- `create*`: used for live document objects, like `createEllipse()`
- `add*`: reserved to create complex structures like Pages and Artboards, adding them to the parent list automatically in a way that may also update the insertion point. Found in `addPage()` and `addArtboard()`.

Speaking of colors, the `ColorUtils` module can output a proper `Color` from either a partial RGB object (where the `alpha` property is optional, defaulting to `1`) or a Hex string with or without alpha, providing the reverse function as well.

```js
const gecko = colorUtils.fromHex("#9de19a"); // alpha is optional
// or
const gecko = colorUtils.fromRGB(157, 225, 154); // alpha is optional
ellipse.fill = editor.makeColorFill(gecko);
const geckoHex = colorUtils.toHex(gecko); // "#9de19aff" 👈 alpha is included
```

### Types matter

CLI versions from `"1.1.1"` onwards now scaffold add-ons with **type definitions** for JavaScript and TypeScript projects. If you're unfamiliar with TypeScript, these additional `.d.ts` and `tsconfig.json` files offer significant benefits. The `.d.ts` files, or _TypeScript declarations_, contain type information about the APIs. They describe the shape of JavaScript objects, providing TypeScript type-checking and autocompletion capabilities (in the form of IntelliSense in VSCode). The `tsconfig.json` files, on the other hand, are configuration files necessary to provide type information for global types in the sandbox runtime. For instance, the sandbox' Console only exposes a subset of the available methods: the `tsconfig.json` file (via `typeRoots`) informs the IntelliSense engine only to show the methods that are actually available.

The bottom line is that `.d.ts` and `tsconfig.json` files in your JavaScript (and TypeScript) projects give code editors knowledge about the Adobe Express document sandbox APIs: it's used to provide code completion and type checking, which can help you avoid errors and write code faster.

![](images/refs-addon-intellisense.png)

<InlineAlert variant="info" slots="text1, text2, text3" />

To use TypeScript declarations in existing projects, install the `@adobe/ccweb-add-on-sdk-types` package.

```sh
npm install @adobe/ccweb-add-on-sdk-types --saveDev
```

The `.d.ts` files can be found in the `node_modules/@adobe/ccweb-add-on-sdk-types` folder.

While IntelliSense is undoubtedly handy, type safety can prevent errors that are otherwise difficult to foresee. Let me show you a revealing example.

Several classes in the Adobe Express DOM have a `children` property, like `GroupNode` or `ArtboardNode`—both implementing the `ContainerNode` interface. Intuitively, their `children` are the contained elements: a group can hold bitmap images, shapes, and whatnot. `ContainerNode` also mandates the implementation of an `allChildren` property, which, apparently, serves the same purpose (we'll get to the difference in a moment).

The type for `children` and `allChildren` is defined as `Iterable<Node>`, where the `Iterable` is basically a collection that supports a `for...of` loop.

```js
for (const node of someIterable) {
  console.log(node.type);
}
```

In _previous versions_ of Adobe Express, the Console would log `allChildren` as an actual _Array_ of Nodes.

![](images/refs-addon-allchildren.png)

If `allChildren` is an Array, the following code will work just fine, won't it?

```js
const selectedNode = editor.context.selection[0];
// If we have a group
if (selectedNode.type === constants.SceneNodeType.group) {
  // Filtering the ellipse shapes
  const ellipses = selectedNode.allChildren.filter(
    // 👈 danger! ❌
    (node) => node.type === constants.SceneNodeType.ellipse
  );
  console.log(`Number of ellipses in this group: ${ellipses.length}`);
}
```

In fact, it _used to work_, but it doesn't anymore; however, it's not Adobe Express' fault. Why, then?

The `allChildren` property is defined in its _contract_ to be of type `Iterable`. The key point here is **the nature of the contract** itself rather than the specific implementation. For instance, when `allChildren` was internally implemented as an Array, this was in line with the contract since Arrays are indeed iterable and support the `for...of` loop. However, Arrays offer additional functionalities _beyond_ the requirements of the `allChildren` contract. Developers should focus on using features that the contract explicitly supports rather than relying on capabilities that might be available in the current implementation of the property but are _outside the contract's scope_. This approach ensures compatibility and reliability, irrespective of the property's underlying implementation changes. If you must use Array methods, convert the iterable with the static method `Array.from()` first.

```js
const ellipses = Array.from(selectedNode.allChildren) // 👈
  .filter((node) => node.type === constants.SceneNodeType.ellipse);
```

To finally unravel the `allChildren` purpose mystery, let's see what the documentation says about it.

> \[...] nodes with a more specific structure can hold children in various discrete "slots"; this `allChildren` list includes _all_ such children and reflects their overall display z-order.

If you inspect a `MediaContainerNode` class, which is instantiated every time you place an image, it has two peculiar properties: `maskShape` and `mediaRectangle`. They hold the shape that masks the bitmap (in UI terms, the Crop—by default, a rectangle with the same image dimensions) and the `ImageRectangleNode` itself. They are the "structures" the documentation refers to; therefore, you'll find them in its `allChildren` property. Other notable examples are `maskShape` in Groups and `artboards` in Pages.

![](images/refs-addon-mediacontainer.png)

## Classes and Interfaces

The Reference documentation does a good job listing all the classes and interfaces that make up the Adobe Express DOM, but there are classification differences worth knowing.

### Live Object classes

Concrete classes like [`RectangleNode`](/references/document-sandbox/document-apis/classes/RectangleNode.md") and [`GroupNode`](/references/document-sandbox/document-apis/classes/GroupNode.md") represent the DOM's **object elements with live setters**. Some of these classes can be instantiated and used directly through factory methods.

```js
import { editor } from "express-document-sdk";

const rect = editor.createRectangle();
const group = editor.createGroup();
group.children.append(rect);
editor.context.insertionParent.children.append(group);
```

Currently, only some classes of this kind have their equivalent `create*` method (for example, `PathNode` lacks it), but it's fair to expect that most of them will, eventually. Live Object classes are the ones whose instances make up the Adobe Express scenegraph: `PageNode`, `ArtboardNode`, `StrokeShapeNode`, `LineNode`, and so on.
A particular case is represented by the `UnknownNode`, which acts as a safety placeholder when dealing with actual DOM objects that don't yet have a corresponding class.

### Collection classes

In Adobe Express, most collections (`children` is a notable example) are expressed as **Lists**: groups of homogeneous elements with properties such as `first`, `last`, and `length`, and dedicated methods like `append()`, `clear()`, etc. They are iterable with `for...of` loops.

Some of these collections are Generic, like `ItemList<T>`, `ReadOnlyItemList<T>`, and `RestrictedItemList<T>`, where the `<T>` means they are designed to be type-agnostic and can work with various data types. The `<T>` acts as a placeholder for the type of objects that the collection will hold or manage.

An implementation of such generic classes is the `ArtboardList` (which subclasses `RestrictedItemList<Artboard>`) and `PageList` (subclassing `RestrictedItemList<Page>`), found respectively in the `PageNode.artboards` and `ExpressRootNode.pages` properties.

### Abstract classes

These are classes that serve as a **base for other classes**. Used by Adobe to rationalize the DOM structure, they provide a common set of properties and methods, but typically cannot be instantiated themselves nor manipulated by add-on developers. Instead, they are meant to be inherited and extended by other subclasses. These subclasses can then implement the abstract class's methods. In the Reference, you can identify abstract classes such as `FillableNode`, `Node`, and `BaseNode`.

### Static classes

`Editor` and `ColorUtils` are special **Singleton classes** that aren't meant to be instantiated or extended; the former acts as the entry point for APIs that read or modify the document's content, whereas the latter provides static utility methods for color manipulation. They are brought into the scope as lowercase named imports from the `"express-document-sdk"`.

```js
import { editor, colorUtils } from "express-document-sdk";
```

### Object (POJO) Interfaces

Such interfaces define the properties of **actual JavaScript objects** that must be created and used, for example, to set a shape's `fill` and `stroke` (respectively, the [`ColorFill`](/references/document-sandbox/document-apis/interfaces/ColorFill.md) or [`Stroke`](/references/document-sandbox/document-apis/interfaces/Stroke.md) interfaces) or fed to utility functions like `colorUtils.fromRGB()` that expect a parameter that implements the [`Color`](/references/document-sandbox/document-apis/interfaces/Color.md) interface. They are the _contracts_ that establish the shape of actual JavaScript objects that developers use in their code. POJO is an acronym that stands for "Plain Old Java Object", which in this context refers to a plain JavaScript object.

### Implementable Interfaces

Implementable interfaces like [`IFillableNode`](/references/document-sandbox/document-apis/interfaces/IFillableNode.md") are only meant to be implemented by classes: they define a contract of properties and methods to which a class must adhere.

In summary, the distinction between all the listed categories lies in their _purpose and usage_: "concrete" classes and object interfaces are used to create actual objects (either JavaScript objects, node instances, or collections), while abstract classes and implementable interfaces provide structure and behaviors that other classes can inherit or implement.

## From theory to practice

Experimenting with newly acquired knowledge is one of the most effective methods to test it. Let's say you have an idea for an add-on that traces the dimensions of the selected object in the style of technical drawings.

![](images/refs-addon-draw.png)

The production of such an add-on would require a number of stages, starting from the MVP (Minimum Viable Product) feature set to the UI. Here, you'll focus exclusively on the DOM prototyping; that is to say, you'll try to figure out the code building blocks by navigating the documentation reference alone—it will be an excellent exercise to get accustomed to it. Every step will be carefully described here; for simplicity, the add-on will be restricted to drawing dimensions on `MediaContainer` objects, assuming no crop has been applied.

To follow along, add one button to the `index.html` file and attach a `drawDimensions()` function to it in `code.js`.

<CodeBlock slots="heading, code" repeat="3" languages="index.html, ui/index.js, documentSandbox/code.js" />

#### UI iframe

```html
<body>
  <sp-theme
    scale="medium"
    color="light"
    theme="express"
  >
    <sp-button id="logNode">Log selected node</sp-button>
    <sp-button id="drawDimensions">Draw Dimensions</sp-button>
  </sp-theme>
</body>
```

#### UI iframe

```js
// ...
addOnUISdk.ready.then(async () => {
  console.log("addOnUISdk is ready for use.");

  // Get the Authoring Sandbox.
  const { runtime } = addOnUISdk.instance;
  const sandboxProxy = await runtime.apiProxy("documentSandbox");

  const buttonIds = ["logNode", "drawDimensions"];
  buttonIds.forEach((id) => {
    const button = document.getElementById(id);
    button.addEventListener("click", () => {
      sandboxProxy[id](); // 👈 attach the function to the button, like:
    }); // sandboxProxy.logNode() or sandboxProxy.drawDimensions()
    button.disabled = false;
  });
});
```

#### Document Sandbox

```js
// ...
function start() {
  runtime.exposeApi({
    logNode: () => {
      /* ... */
    },
    drawDimensions: () => {
      // ...
    },
  });
}
```

### Getting the context

The first part is to get and validate the selected node. There's a promising [`Context`](/references/document-sandbox/document-apis/classes/Context.md) class in the reference documentation that _"contains the user's current selection state, indicating the content they are focused on"_. Excellent! But how can you access it, though? The [`Editor`](/references/document-sandbox/document-apis/classes/Editor.md) class is the Document API entry point; it may be worth paying a visit to its page. Lo and behold, it exposes a context property, which returns a context instance: you can use it to check if there's a selection and whether it's of the right type—`hasSelection` and `selection` will do the job.

```js
import { editor, constants, colorUtils } from "express-document-sdk";

runtime.exposeApi({
  drawDimensions: () => {
    if (
      editor.context.hasSelection &&
      editor.context.selection[0].type ===
        constants.SceneNodeType.mediaContainer
    ) {
      // ...
    }
  },
});
```

Please note the use of the [`SceneNodeType`](/references/document-sandbox/document-apis/enumerations/SceneNodeType.md) constant, as discussed earlier, instead of the `"MediaContainer"` string literal.

### Getting the dimensions

Now that you've made sure only the right kind of node is handled, let's get its dimensions; since you'll need to draw a line, it may be helpful to have its coordinates in space (relative to its parent container) as well. According to the reference, the [`MediaContainerNode`](/references/document-sandbox/document-apis/classes/MediaContainerNode.md) class provides a [`translation`](/references/document-sandbox/document-apis/classes/MediaContainerNode.md#translation) property that returns an object with `x` and `y` properties, which you need. There are no `width` and `height`, though; where to look? `MediaContainerNode` also features a [`mediaRectangle`](/references/document-sandbox/document-apis/classes/MediaContainerNode.md#mediarectangle) property, which, upon inspection, is of type [`ImageRectangleNode`](/references/document-sandbox/document-apis/classes/ImageRectangleNode.md): this holds the actual media and offers both `width` and `height` properties. In future versions, Adobe Express will make available a proper `bounds` object for this purpose.

```js
if ( /* ... */ ) {
  // grabbing the selected node
  const selectedNode = editor.context.selection[0];
  // getting its coordinates
  const nodeTranslation = selectedNode.translation;
  // getting its dimensions from the mediaRectangle, destucturing and renaming them on the fly
  const { width: nodeWidth, height: nodeHeight } = selectedNode.mediaRectangle;
}
```

### Drawing a line

Time to draw the line. The [`Editor`](/references/document-sandbox/document-apis/classes/Editor.md) class includes a [`createLine()`](/references/document-sandbox/document-apis/classes/Editor.md#createline) factory method, which returns a [`LineNode`](/references/document-sandbox/document-apis/classes/LineNode.md) instance. The `LineNode` class, you learn from the reference, has `startX`, `startY`, `endX`, and `endY` properties: they only implement the getter, though—hence, are read-only. Scrolling through the methods, you find [`setEndPoints()`](/references/document-sandbox/document-apis/classes/LineNode.md#setendpoints), which expects the same parameters and is used as a setter for them.

```js
// ...
const hLine = editor.createLine();
hLine.setEndPoints(
  nodeTranslation.x,
  nodeTranslation.y - 20,
  nodeTranslation.x + nodeWidth,
  nodeTranslation.y - 20
);
```

Here, an arbitrary 20px margin is added between the horizontal line and the selected node; this could very well be a parameter chosen by the user from a UI control you can add later. The line is extended to a `nodeWidth` length, i.e., the `mediaRectangle`'s. You can finally add it to the scenegraph.

```js
editor.context.insertionParent.children.append(hLine);
```

<InlineAlert variant="info" slots="text1, text2" />

Please note that, according to the documentation, `translation` is **relative to the node's parent container**: in other words, you're capturing the position of the `MediaContainerNode` with respect to its parent. How can you be sure, then, that the line will be drawn in the right place?

The answer is that the `insertionParent` property of the `Editor` class—that you use to append the `hLine`—is a special node that always points to the current insertion point in the scenegraph. In this case, you're adding the line to the same parent container of the selected node, so `hLine` will be positioned correctly with respect to the object it measures: both the `MediaContainerNode` and the `LineNode` will be `children` of _the same parent_, therefore sharing _the same relative coordinate space_.

The line is there, but it lacks the proper endpoints. The reference helps us out again: the `LineNode` has a [`startArrowHeadType`](/references/document-sandbox/document-apis/classes/LineNode.md#startarrowheadtype) and [`endArrowHeadType`](/references/document-sandbox/document-apis/classes/LineNode.md#endarrowheadtype) properties, whose value is an enumerable provided by the [`ArrowHeadType`](/references/document-sandbox/document-apis/enumerations/ArrowHeadType.md) constant.[^3] There are several options available: let's pick `triangularFilled`.

```js
// ...
hLine.startArrowHeadType = hLine.endArrowHeadType =
  constants.ArrowHeadType.triangularFilled;
```

As live objects, setting all the properties before or after appending the line to the scenegraph doesn't really matter; the result is the same.

### Adding the text

Next up, you need to add the text. The `Editor` class provides a [`createText()`](/references/document-sandbox/document-apis/classes/Editor.md#createtext) method, which returns a [`TextNode`](/references/document-sandbox/document-apis/classes/TextNode.md) instance. The `TextNode` class has a [`text`](/references/document-sandbox/document-apis/classes/TextNode.md#text) property, which expects a string. Mind you, the setter implements parameter validation; if you were to assign a number, it would throw an error.

```js
// ...
const hText = editor.createText();
hText.fullContent.text = `${Math.trunc(nodeWidth).toString()}px`;
editor.context.insertionParent.children.append(hText);
```

The text appears on the top-left corner of the document, which is the default insertion point. `setPositionInParent()` would be perfect to move it to the right spot, just above the line. At the time of this writing, a `TextNode` doesn't feature `width` and `height` properties, which would be helpful to set an appropriate `localRegistrationPoint`; hence, you'll have to do with `translation`.

```js
// ...
hText.translation = {
  x: nodeTranslation.x + nodeWidth / 2,
  y: nodeTranslation.y - 30,
};
```

An extra 10 pixels padding from the line has been added, but this could also be a parameter. Let's group the line and the text together to move them around as a single entity. The `Editor` class provides a [`createGroup()`](/references/document-sandbox/document-apis/classes/Editor.md#creategroup) method, which returns a [`GroupNode`](/references/document-sandbox/document-apis/classes/GroupNode.md) instance. The `GroupNode` class provides a `children` property: you can `append()` both the line and the text to it.

```js
// ...
const hGroup = editor.createGroup();
editor.context.insertionParent.children.append(hGroup);
hGroup.children.append(hLine, hText);
```

### Repeating the process

From this point, creating the vertical line and the text is a matter of copying/pasting and changing a few parameters. The only new element may be text rotation: the `TextNode` class has a [`setRotationInParent()`](/references/document-sandbox/document-apis/classes/TextNode.md#setrotationinparent) method. It expects a number in degrees (-90, in our case) and a `localRotationPoint` object (implementing the [`Point`](/references/document-sandbox/document-apis/interfaces/Point/) interface), which is the point to rotate around in the node's local coordinates. In this case, `{x: 0, y: 0}` will do.

```js
const vText = editor.createText();
vText.fullContent.text = `${Math.trunc(nodeHeight).toString()}px`;
editor.context.insertionParent.children.append(vText);

vText.translation = {
  x: nodeTranslation.x - 30,
  y: nodeTranslation.y + nodeHeight / 2,
};
vText.setRotationInParent(-90, { x: 0, y: 0 }); // 👈
```

### Refactoring and optimizing the code

In the final add-on code, there are three buttons: one logs the selected node, one draws the dimensions as you've just seen, and the last one is a refactored version that also draws dashed lines (red and thinner) connecting the dimensions to the object's corners.

![](images/refs-addon-refactor.png)

For brevity's sake, only a few relevant additions to the code will be mentioned below—please refer to the [full sample](#final-project) for the complete picture.

The code for drawing the dimensions is moved to a separate `dimensions.js` file. This update includes exporting `drawDimensions()` and `drawDimensionsRefactored()` alongside the implementation of a private `createDimensionLine()`. This function abstracts the creation of a line and its accompanying text by accepting `width`, `height`, `translation`, `orientation`, and `margin` within an options object.

<CodeBlock slots="heading, code" repeat="1" languages="documentSandbox/dimensions.js" />

#### documentSandbox/dimensions.js

```js
// ...
const createDimensionLine = ({
  width,
  height,
  translation,
  orientation,
  margin,
}) => {
  /* ... */
};

// ...
const drawDimensions = () => {
  /* ... */
};
const drawDimensionsRefactored = () => {
  // ...
  createDimensionLine({
    /* ... */
  }); // 👈
  createDimensionLine({
    /* ... */
  }); // 👈
  // ...
};

export { drawDimensions, drawDimensionsRefactored };
```

A rather unorthodox warning system is implemented to alert the user when selecting an unsupported node type. Through the Communication API outlined in [this tutorial](/guides/tutorials/stats-addon.md), a `flashWrongElement()` function, defined in the iframe UI, is available to the Document Sandbox.

<CodeBlock slots="heading, code" repeat="2" languages="ui/index.js, documentSandbox/dimensions.js" />

#### ui/index.js

```js
addOnUISdk.ready.then(async () => {
  // ...
  runtime.exposeApi({
    flashWrongElement(id) {
      const button = document.getElementById(id);
      const oldText = button.textContent;
      const oldColor = button.style.backgroundColor;

      button.textContent = "WRONG NODE";
      button.style.backgroundColor = "#ff0000";

      setTimeout(() => {
        button.textContent = oldText;
        button.style.backgroundColor = oldColor;
      }, 1000);
    },
  });
});
```

#### documentSandbox/dimensions.js

```js
const drawDimensionsRefactored = () => {
  if (
    editor.context.hasSelection &&
    editor.context.selection[0].type === constants.SceneNodeType.mediaContainer
  ) {
    // ...
  } else {
    panelUIProxy.flashWrongElement("drawDimensionsRefactored"); // 👈
  }
};
```

When the Document Sandbox code detects an unsupported node type, it reaches out to the iframe UI `flashWrongElement()` method (exposed via proxy), sending the button `id` as a parameter. As a result, the button blinks red for a second, as its CSS and `textContent` property are temporarily changed.

![](images/refs-addon-unsupported.png)

### Next Steps

As an exercise, you use the code sample found below and expand it to build a more complete Dimensions add-on; for example, you can:

- support **more node types**;
- add **UI elements**:
  - a slider to control the dimensions' distance from the object;
  - dropdowns to choose the line's style (solid, dashed, dotted), and the arrowhead type;
  - a checkbox to toggle the extra dashed lines;
  - a color picker to change the line's color—see the [Grids add-on](/guides/tutorials/grids-addon.md) for an example.

## Lessons Learned

Let's review the key concepts discussed in this article.

- **DOM Structure**: the DOM is a hierarchical tree of nodes with parent/child relationships and well-defined inheritance.
- **OOP principles**: classes, inheritance, class extension, and interfaces are crucial Object Oriented programming notions.
- **Constants**: represent a safe way to refer to internal values and check against enumerable properties.
- **Reference documentation**: the Adobe Express Document API reference is a key resource: it provides comprehensive information on available classes, interfaces, and their properties and methods.
- **Classes and Interfaces**: you can differentiate between live object classes, collection classes, abstract classes, static classes, object interfaces, and implementable interfaces.
- **Types and IntelliSense**: using `.d.ts` and `tsconfig.json` files in your projects can enhance code completion and type checking, leading to faster and error-free coding.
- You've also learned how to **prototype an add-on** by navigating the Reference documentation alone.

## Final Project

The code for this project can be found below, as well as in the [`express-add-on-samples`](https://github.com/AdobeDocs/express-add-on-samples) repository.

<InlineAlert variant="info" slots="text1" />

Please use the **iframe UI** and **Document Sandbox** tabs to switch between the two domains and find a dropdown in the top-right corner to select which file to show.

<CodeBlock slots="heading, code" repeat="4" languages="index.html, ui/index.js, documentSandbox/code.js, documentSandbox/dimensions.js" />

#### iframe UI

```html
<body>
  <sp-theme
    scale="medium"
    color="light"
    theme="express"
  >
    <sp-button id="logNode">Log selected node</sp-button>
    <sp-button id="drawDimensions">Draw Dimensions</sp-button>
    <sp-button id="drawDimensionsRefactored"
      >Draw Dimensions (refactored)</sp-button
    >
  </sp-theme>
</body>
```

#### iframe UI

```js
import "@spectrum-web-components/styles/typography.css";
import "@spectrum-web-components/theme/src/themes.js";
import "@spectrum-web-components/theme/theme-light.js";
import "@spectrum-web-components/theme/express/theme-light.js";
import "@spectrum-web-components/theme/express/scale-medium.js";
import "@spectrum-web-components/theme/sp-theme.js";

import "@spectrum-web-components/button/sp-button.js";

import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  console.log("addOnUISdk is ready for use.");

  // Get the Authoring Sandbox.
  const { runtime } = addOnUISdk.instance;
  const sandboxProxy = await runtime.apiProxy("documentSandbox");

  const buttonIds = ["logNode", "drawDimensions", "drawDimensionsRefactored"];

  buttonIds.forEach((id) => {
    const button = document.getElementById(id);
    button.addEventListener("click", () => {
      sandboxProxy[id]();
    });
    button.disabled = false;
  });

  runtime.exposeApi({
    flashWrongElement(id) {
      const button = document.getElementById(id);
      const oldText = button.textContent;
      const oldColor = button.style.backgroundColor;

      button.textContent = "WRONG NODE";
      button.style.backgroundColor = "#ff0000";

      setTimeout(() => {
        button.textContent = oldText;
        button.style.backgroundColor = oldColor;
      }, 1000);
    },
  });
});
```

#### Document Sandbox

```js
import addOnSandboxSdk from "add-on-sdk-document-sandbox";
const { runtime } = addOnSandboxSdk.instance;
import { editor } from "express-document-sdk";
import { drawDimensions, drawDimensionsRefactored } from "./dimensions.js";

function start() {
  runtime.exposeApi({
    drawDimensions,
    drawDimensionsRefactored,
    logNode: () => {
      const selectedNode = editor.context.selection[0];
      console.log("Currently selected node", selectedNode);
    },
  });
}

start();
```

#### Document Sandbox

```js
import addOnSandboxSdk from "add-on-sdk-document-sandbox";
const { runtime } = addOnSandboxSdk.instance;
const panelUIProxy = await runtime.apiProxy("panel");

import { editor, constants } from "express-document-sdk";

const createDimensionLine = ({
  width,
  height,
  translation,
  orientation,
  margin,
}) => {
  const isVertical = orientation === "vertical";

  // Adjust line start and end points based on orientation and margin
  const lineStart = isVertical
    ? { x: translation.x - margin, y: translation.y }
    : { x: translation.x, y: translation.y - margin };
  const lineEnd = isVertical
    ? { x: translation.x - margin, y: translation.y + height }
    : { x: translation.x + width, y: translation.y - margin };

  const textValue = isVertical ? height : width;
  const textPos = isVertical
    ? { x: translation.x - margin - 10, y: translation.y + height / 2 }
    : { x: translation.x + width / 2, y: translation.y - margin - 10 };

  const line = editor.createLine();
  line.setEndPoints(lineStart.x, lineStart.y, lineEnd.x, lineEnd.y);
  line.startArrowHeadType = line.endArrowHeadType =
    constants.ArrowHeadType.openTriangular;
  editor.context.insertionParent.children.append(line);

  const text = editor.createText();
  text.fullContent.text = `${Math.trunc(textValue).toString()}px`;
  editor.context.insertionParent.children.append(text);
  text.translation = textPos;

  if (isVertical) {
    text.setRotationInParent(-90, { x: 0, y: 0 });
  }

  const group = editor.createGroup();
  editor.context.insertionParent.children.append(group);
  group.children.append(line, text);

  // Create and append extra lines at the extremities
  for (let i = 0; i < 2; i++) {
    const extraLine = editor.createLine();
    const extraLineStart = isVertical
      ? {
          x: translation.x,
          y: i === 0 ? translation.y : translation.y + height,
        }
      : {
          x: i === 0 ? translation.x : translation.x + width,
          y: translation.y,
        };
    const extraLineEnd = isVertical
      ? {
          x: translation.x - margin - 10,
          y: i === 0 ? translation.y : translation.y + height,
        }
      : {
          x: i === 0 ? translation.x : translation.x + width,
          y: translation.y - margin - 10,
        };

    extraLine.setEndPoints(
      extraLineStart.x,
      extraLineStart.y,
      extraLineEnd.x,
      extraLineEnd.y
    );
    extraLine.stroke = editor.makeStroke({
      color: { red: 1, green: 0, blue: 0, alpha: 1 },
      dashPattern: [4, 2],
      width: 0.5,
    });
    group.children.append(extraLine);
    // editor.context.insertionParent.children.append(extraLine);
  }

  return group;
};

const drawDimensions = () => {
  if (
    editor.context.hasSelection &&
    editor.context.selection[0].type === constants.SceneNodeType.mediaContainer
  ) {
    const selectedNode = editor.context.selection[0];
    console.log(selectedNode);
    const { translation: nodeTranslation } = selectedNode;
    const { width: nodeWidth, height: nodeHeight } =
      selectedNode.mediaRectangle;

    const hLine = editor.createLine();
    hLine.setEndPoints(
      nodeTranslation.x,
      nodeTranslation.y - 20,
      nodeTranslation.x + nodeWidth,
      nodeTranslation.y - 20
    );

    // translation is relative to the parent!!
    editor.context.insertionParent.children.append(hLine);
    hLine.startArrowHeadType = hLine.endArrowHeadType =
      constants.ArrowHeadType.openTriangular;

    const hText = editor.createText();
    hText.fullContent.text = `${Math.trunc(nodeWidth).toString()}px`;
    editor.context.insertionParent.children.append(hText);

    hText.translation = {
      x: nodeTranslation.x + nodeWidth / 2,
      y: nodeTranslation.y - 30,
    };

    const hGroup = editor.createGroup();
    editor.context.insertionParent.children.append(hGroup);
    hGroup.children.append(hLine, hText);

    // Same for the vertical line
    const vLine = editor.createLine();
    vLine.setEndPoints(
      nodeTranslation.x - 20,
      nodeTranslation.y,
      nodeTranslation.x - 20,
      nodeTranslation.y + nodeHeight
    );
    vLine.startArrowHeadType = vLine.endArrowHeadType =
      constants.ArrowHeadType.openTriangular;

    editor.context.insertionParent.children.append(vLine);

    const vText = editor.createText();
    vText.fullContent.text = `${Math.trunc(nodeHeight).toString()}px`;
    editor.context.insertionParent.children.append(vText);

    vText.translation = {
      x: nodeTranslation.x - 30,
      y: nodeTranslation.y + nodeHeight / 2,
    };
    vText.setRotationInParent(-90, { x: 0, y: 0 });

    const vGroup = editor.createGroup();
    editor.context.insertionParent.children.append(vGroup);
    vGroup.children.append(vLine, vText);
  } else {
    panelUIProxy.flashWrongElement("drawDimensions");
  }
};

const drawDimensionsRefactored = () => {
  if (
    editor.context.hasSelection &&
    editor.context.selection[0].type === constants.SceneNodeType.mediaContainer
  ) {
    const selectedNode = editor.context.selection[0];
    const { translation: nodeTranslation } = selectedNode;
    const { width: nodeWidth, height: nodeHeight } =
      selectedNode.mediaRectangle;

    // Create horizontal dimension line
    createDimensionLine({
      width: nodeWidth,
      height: nodeHeight,
      translation: nodeTranslation,
      orientation: "horizontal",
      margin: 60,
    });

    // Create vertical dimension line
    createDimensionLine({
      width: nodeWidth,
      height: nodeHeight,
      translation: nodeTranslation,
      orientation: "vertical",
      margin: 20,
    });
  } else {
    panelUIProxy.flashWrongElement("drawDimensionsRefactored");
  }
};

export { drawDimensions, drawDimensionsRefactored };
```

---

[^1]: Creating entirely novel features for desktop applications typically involves using SDKs and low-level languages such as C++. Adobe Express doesn't allow for this kind of customization.
[^2]: Typically, not every feature available in an application is by default surfaced to Scripting—it's not uncommon for it to be a smaller subset of the UI, features-wise.
[^3]: At the time of this writing, these properties are _not yet_ available for selection in the Adobe Express user interface. It's one of those rare cases where scripting is mightier than the UI!
[@express-document-sdk](../overview.md) / ArrowHeadType

# Enumeration: ArrowHeadType

<InlineAlert slots="text" variant="warning"/>

_Do not depend on the literal numeric values of these constants_, as they may change. Always reference the enum identifiers in your code.

## Enumeration Members

### circleFilled

• **circleFilled**: `21`

---

### circleHollow

• **circleHollow**: `24`

---

### none

• **none**: `0`

---

### openTriangular

• **openTriangular**: `11`

---

### squareFilled

• **squareFilled**: `22`

---

### squareHollow

• **squareHollow**: `25`

---

### triangularFilled

• **triangularFilled**: `7`

---

### verticalLine

• **verticalLine**: `27`
[@express-document-sdk](../overview.md) / BlendMode

# Enumeration: BlendMode

<InlineAlert slots="text" variant="warning"/>

_Do not depend on the literal numeric values of these constants_, as they may change. Always reference the enum identifiers in your code.

Determines how a scenenode is composited on top of the content rendered below it.

If a node is inside a container whose blend mode anything other than [passThrough](BlendMode.md#passthrough), then the node's blend mode only
interacts with other siblings within the same container. See documentation below for details.

## Enumeration Members

### color

• **color**: `16`

---

### colorBurn

• **colorBurn**: `5`

---

### colorDodge

• **colorDodge**: `8`

---

### darken

• **darken**: `4`

---

### difference

• **difference**: `12`

---

### exclusion

• **exclusion**: `13`

---

### hardLight

• **hardLight**: `11`

---

### hue

• **hue**: `14`

---

### lighten

• **lighten**: `6`

---

### luminosity

• **luminosity**: `17`

---

### multiply

• **multiply**: `3`

---

### normal

• **normal**: `2`

The normal, default blend mode for leaf nodes.

Note: Group nodes default to using `passThrough` blend mode instead. See below.

---

### overlay

• **overlay**: `9`

---

### passThrough

• **passThrough**: `1`

This blend mode only applies to container nodes with children; for leaf nodes, it is treated the same as `normal`.

In this mode, the container has no particular blend mode of its own, but rather each individual child of the container
will be individually composited onto the background using its own specific blend mode. In _any other_ blend mode, the
children are first rendered in an "isolation mode" and then the flattened result is composited onto other content
below it using solely the container's own blend mode.

Group nodes are set to `passThrough` by default.

---

### saturation

• **saturation**: `15`

---

### screen

• **screen**: `7`

---

### softLight

• **softLight**: `10`
[@express-document-sdk](../overview.md) / EditorEvent

# Enumeration: EditorEvent

This enum represents the supported editor events.

## Enumeration Members

### selectionChange

• **selectionChange**: `"selectionChange"`
[@express-document-sdk](../overview.md) / FillRule

# Enumeration: FillRule

<InlineAlert slots="text" variant="warning"/>

_Do not depend on the literal numeric values of these constants_, as they may change. Always reference the enum identifiers in your code.

The fill rule, aka "winding rule," specifies how the interior area of a path is determined in cases where the path is
self-intersecting or contains separate, nested closed loops.

## Enumeration Members

### evenOdd

• **evenOdd**: `1`

---

### nonZero

• **nonZero**: `0`
[@express-document-sdk](../overview.md) / FillType

# Enumeration: FillType

<InlineAlert slots="text" variant="warning"/>

_Do not depend on the literal string values of these constants_, as they may change. Always reference the enum identifiers in your code.

<InlineAlert slots="text" variant="warning"/>

_Additional fill types may be added in the future._ If your code has different branches or cases depending on fill type,
always have a default/fallback case to handle any unknown values you may encounter.

## Enumeration Members

### color

• **color**: `"Color"`

A solid color fill.
[@express-document-sdk](../overview.md) / SceneNodeType

# Enumeration: SceneNodeType

<InlineAlert slots="text" variant="warning"/>

_Do not depend on the literal string values of these constants_, as they may change. Always reference the enum identifiers in your code.

<InlineAlert slots="text" variant="warning"/>

_Additional node types may be added in the future._ If your code has different branches or cases depending on node type,
always have a default/fallback case to handle any unknown values you may encounter.

## Enumeration Members

### artboard

• **artboard**: `"ab:Artboard"`

---

### artworkRoot

• **artworkRoot**: `"ArtworkRoot"`

---

### complexShape

• **complexShape**: `"ComplexShape"`

Type of ComplexShapeNode, representing a complex prepackaged shape with fill and stroke, that appears as a leaf node in the UI

---

### ellipse

• **ellipse**: `"Ellipse"`

---

### gridCell

• **gridCell**: `"GridCell"`

Type of MediaContainerNode which is a child of a GridLayout, representing one of the Grid's cells

---

### gridLayout

• **gridLayout**: `"GridLayout"`

Type of GridLayoutNode represents a grid layout in the scenegraph used to create a layout grid that other content can be placed into

---

### group

• **group**: `"Group"`

---

### imageRectangle

• **imageRectangle**: `"ImageRectangle"`

Type of MediaContainerNode's "media rectangle" child when it is holding an image

---

### line

• **line**: `"Line"`

---

### linkedAsset

• **linkedAsset**: `"LinkedAsset"`

---

### mediaContainer

• **mediaContainer**: `"MediaContainer"`

Type of MediaContainerNode, representing the top-level container of the multi-node construct used to display images or video.

---

### page

• **page**: `"Page"`

Type of PageNode

---

### path

• **path**: `"Path"`

---

### polygon

• **polygon**: `"artgr:Polygon"`

---

### rectangle

• **rectangle**: `"Rectangle"`

---

### solidColorShape

• **solidColorShape**: `"SolidColorShape"`

Type of SolidColorShapeNode, representing a solid-color prepackaged shape that appears as a leaf node in the UI

---

### strokeShape

• **strokeShape**: `"StrokeShape"`

Type of StrokeShapeNode, representing a stroke-only prepackaged shape that appears as a leaf node in the UI

---

### text

• **text**: `"Text"`

Type of TextNode, representing a non-threaded text or a threaded text frame
[@express-document-sdk](../overview.md) / StrokePosition

# Enumeration: StrokePosition

<InlineAlert slots="text" variant="warning"/>

_Do not depend on the literal numeric values of these constants_, as they may change. Always reference the enum identifiers in your code.

A stroke's Stroke.position determines how the thickness of the stroke is aligned along a shape's path outline.

## Enumeration Members

### center

• **center**: `0`

---

### inside

• **inside**: `1`

---

### outside

• **outside**: `2`
[@express-document-sdk](../overview.md) / StrokeType

# Enumeration: StrokeType

<InlineAlert slots="text" variant="warning"/>

_Do not depend on the literal string values of these constants_, as they may change. Always reference the enum identifiers in your code.

<InlineAlert slots="text" variant="warning"/>

_Additional stroke types may be added in the future._ If your code has different branches or cases depending on stroke type,
always have a default/fallback case to handle any unknown values you may encounter.

## Enumeration Members

### color

• **color**: `"Color"`

A solid-color stroke, with optional dashes.
[@express-document-sdk](../overview.md) / TextAlignment

# Enumeration: TextAlignment

<InlineAlert slots="text" variant="warning"/>

_Do not depend on the literal numeric values of these constants_, as they may change. Always reference the enum identifiers in your code.

## Enumeration Members

### center

• **center**: `3`

---

### left

• **left**: `1`

---

### right

• **right**: `2`
[@express-document-sdk](../overview.md) / TextType

# Enumeration: TextType

<InlineAlert slots="text" variant="warning"/>

_Do not depend on the literal numeric values of these constants_, as they may change. Always reference the enum identifiers in your code.

## Enumeration Members

### area

• **area**: `1`

---

### autoHeight

• **autoHeight**: `2`

Soft bottom

---

### autoWidth

• **autoWidth**: `3`

Point text

---

### circular

• **circular**: `4`

---

### magicFit

• **magicFit**: `5`
[@express-document-sdk](../overview.md) / VisualEffectType

# Enumeration: VisualEffectType

Visual effects that can be applied to a text node.

## Enumeration Members

### generativeTextEffects

• **generativeTextEffects**: `"GenerativeTextEffects"`

---

### outline

• **outline**: `"Outline"`

---

### shadow

• **shadow**: `"Shadow"`

---

### shapeDecoration

• **shapeDecoration**: `"ShapeDecoration"`
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: Document APIs
description: An introduction to the Document APIs available in the document sandbox.
contributors:
  - https://github.com/hollyschinsky  
hideBreadcrumbNav: true
---

# Document APIs

The [Document APIs](./classes/Editor.md) provide access to the user's document, allowing you to access the document structure and properties, and apply changes to it via the provided APIs.

## Overview

Some examples of what you can do with the [Adobe Express Document APIs](./classes/Editor.md) are creating shapes, adding pages to the document, clearing the artboard and more. See the following sections for more details and examples of using these new APIs.

## Access to Express Document APIs

An exported `editor` module is provided to enable access to the [Document APIs](./classes/Editor.md). You can simply import this module into your script file code to access the methods provided below. For example:

```js
import { editor } from "express-document-sdk"; // named import 'editor' from express-document-sdk module
```

See the example below for further usage details.

## Example Code Snippet

The following code snippet illustrates how to use the [Express Document APIs](./classes/Editor.md) from the document sandbox code running in your `code.js` for instance, to access the current document, create a rectangle, set some properties and a fill for the rectangle, and finally, add it to the document:

```js
import { editor, colorUtils } from "express-document-sdk";

const insertionParent = editor.context.insertionParent; // get node to insert content into

const rectangle = editor.createRectangle();
rectangle.width = 200;
rectangle.height = 150;
rectangle.translation = { x: 100, y: 20 };
console.log(rectangle); // for debugging purpose

const [red, green, blue, alpha] = [0.8, 0.6, 0.2, 0.7];
// Note: alpha param is optional
const aColor = colorUtils.fromRGB(red,green,blue,alpha)
const rectangleFill = editor.makeColorFill(aColor);
rectangle.fill = rectangleFill;

insertionParent.children.append(rectangle);
```

## Tutorials, References & Code Samples

Please see [this extensive tutorial](../../../guides/tutorials/grids-addon.md) provided to help you build your first add-on using the Document APIs in our [tutorials section](../../../guides/tutorials/). Also be sure to check out the [full set of API documentation](/express-add-on-apis/docs/api/classes/Editor) as well as the [editor-apis](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/editor-apis) and [image-and-page](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/image-and-page) code samples provided in the [document sandbox samples](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples) for more details on using the [Document APIs](./classes/Editor.md).
[@express-document-sdk](../overview.md) / AreaTextLayout

# Interface: AreaTextLayout

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

## Properties

### height

• **height**: `number`

The height of the text node in pixels.

---

### type

• **type**: [`area`](../enumerations/TextType.md#area)

---

### width

• **width**: `number`

The width of the text node in pixels.
[@express-document-sdk](../overview.md) / AutoHeightTextLayout

# Interface: AutoHeightTextLayout

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

## Properties

### type

• **type**: [`autoHeight`](../enumerations/TextType.md#autoheight)

---

### width

• **width**: `number`

The width of the text node in pixels.
[@express-document-sdk](../overview.md) / BaseParagraphStyles

# Interface: BaseParagraphStyles

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

Base paragraph styles that can be applied to an entire paragraph atomically.
Excludes list style settings, which differ between the getter-oriented [ParagraphStyles](ParagraphStyles.md) interface and the
setter-oriented [ParagraphStylesRangeInput](ParagraphStylesRangeInput.md).

## Extended by

-   [`ParagraphStyles`](ParagraphStyles.md)

## Properties

### lineSpacing

• **lineSpacing**: `number`

Spacing between lines, aka leading, expressed as a multiple of the font size's default spacing - ex. 1.5 = 150% of normal.
It only affects the space *between* lines, not the space above the first line or below the last line.

---

### spaceAfter

• **spaceAfter**: `number`

Space after paragraph (in points). It does not affect the last paragraph. It is additive to the next paragraph's spaceBefore
(adjacent spacing does not merge/collapse together).

---

### spaceBefore

• **spaceBefore**: `number`

Space before paragraph (in points). It does not affect the first paragraph. It is additive to previous paragraph's spaceAfter
(adjacent spacing does not merge/collapse together).
[@express-document-sdk](../overview.md) / BitmapImage

# Interface: BitmapImage

Represents a bitmap image resource. Use [Editor.loadBitmapImage](../classes/Editor.md#loadbitmapimage) to create a BitmapImage, and then [Editor.createImageContainer](../classes/Editor.md#createimagecontainer)
to display it in the document by creating a MediaContainerNode structure.

## Properties

### height

• `readonly` **height**: `number`

Original height of the bitmap in pixels.

---

### width

• `readonly` **width**: `number`

Original width of the bitmap in pixels.
[@express-document-sdk](../overview.md) / CharacterStyles

# Interface: CharacterStyles

Text styles that can be applied to any range of characters, even a short span like a single word. (Contrast with
ParagraphStyles, which must be applied to an entire paragraph atomically).

## Extends

-   `BaseCharacterStyles`

## Extended by

-   [`CharacterStylesRange`](CharacterStylesRange.md)

## Properties

### color

• **color**: [`Color`](Color.md)

Text color.

#### Inherited from

`BaseCharacterStyles.color`

---

### font

• **font**: [`Font`](../type-aliases/Font.md)

---

### fontSize

• **fontSize**: `number`

Size of the text in points.

#### Inherited from

`BaseCharacterStyles.fontSize`

---

### letterSpacing

• **letterSpacing**: `number`

Uniformly adjusts the letter spacing, aka character spacing. Specified as a delta relative to the font's default
spacing, in units of 1/1000 em: positive values increase the spacing, negative values tighten the spacing, and 0
leaves spacing at its default.

#### Inherited from

`BaseCharacterStyles.letterSpacing`

---

### underline

• **underline**: `boolean`

Adds an underline to text.

#### Inherited from

`BaseCharacterStyles.underline`
[@express-document-sdk](../overview.md) / CharacterStylesInput

# Interface: CharacterStylesInput

Variant of [CharacterStyles](CharacterStyles.md) with all style fields optional, used for applyCharacterStyles(). When using that API,
any fields not specified are left unchanged, preserving the text's existing styles.

If specified, the font must be of the [AvailableFont](../classes/AvailableFont.md) type – one that is guaranteed to be available for the current
user to edit with.

## Extends

-   `Partial`<`BaseCharacterStyles`\>

## Extended by

-   [`CharacterStylesRangeInput`](CharacterStylesRangeInput.md)

## Properties

### color?

• `optional` **color**: [`Color`](Color.md)

Text color.

#### Inherited from

`Partial.color`

---

### font?

• `optional` **font**: [`AvailableFont`](../classes/AvailableFont.md)

---

### fontSize?

• `optional` **fontSize**: `number`

Size of the text in points.

#### Inherited from

`Partial.fontSize`

---

### letterSpacing?

• `optional` **letterSpacing**: `number`

Uniformly adjusts the letter spacing, aka character spacing. Specified as a delta relative to the font's default
spacing, in units of 1/1000 em: positive values increase the spacing, negative values tighten the spacing, and 0
leaves spacing at its default.

#### Inherited from

`Partial.letterSpacing`

---

### underline?

• `optional` **underline**: `boolean`

Adds an underline to text.

#### Inherited from

`Partial.underline`
[@express-document-sdk](../overview.md) / CharacterStylesRange

# Interface: CharacterStylesRange

A set of [CharacterStyles](CharacterStyles.md) along with the range of characters they apply to. Seen in the characterStyleRanges getter.

Note that fonts returned by the getter are *not* guaranteed to be ones the user has rights to edit with, even though they
are visible in the document.

## Extends

-   [`CharacterStyles`](CharacterStyles.md).[`StyleRange`](StyleRange.md)

## Properties

### color

• **color**: [`Color`](Color.md)

Text color.

#### Inherited from

[`CharacterStyles`](CharacterStyles.md).[`color`](CharacterStyles.md#color)

---

### font

• **font**: [`Font`](../type-aliases/Font.md)

#### Inherited from

[`CharacterStyles`](CharacterStyles.md).[`font`](CharacterStyles.md#font)

---

### fontSize

• **fontSize**: `number`

Size of the text in points.

#### Inherited from

[`CharacterStyles`](CharacterStyles.md).[`fontSize`](CharacterStyles.md#fontsize)

---

### length

• **length**: `number`

The length or number of characters in which character styles will be applied.
Note: since characters are represented as UTF-16 code units, some symbols
such as emojis are considered to have a length of 2.

#### Inherited from

[`StyleRange`](StyleRange.md).[`length`](StyleRange.md#length)

---

### letterSpacing

• **letterSpacing**: `number`

Uniformly adjusts the letter spacing, aka character spacing. Specified as a delta relative to the font's default
spacing, in units of 1/1000 em: positive values increase the spacing, negative values tighten the spacing, and 0
leaves spacing at its default.

#### Inherited from

[`CharacterStyles`](CharacterStyles.md).[`letterSpacing`](CharacterStyles.md#letterspacing)

---

### underline

• **underline**: `boolean`

Adds an underline to text.

#### Inherited from

[`CharacterStyles`](CharacterStyles.md).[`underline`](CharacterStyles.md#underline)
[@express-document-sdk](../overview.md) / CharacterStylesRangeInput

# Interface: CharacterStylesRangeInput

Variant of [CharacterStylesRange](CharacterStylesRange.md) with all style fields optional, along with the range of characters they apply to.
Used for the characterStyleRanges setter. When invoking the setter, any fields not specified are reset to their defaults.

If specified, the font must be of the [AvailableFont](../classes/AvailableFont.md) type – one that is guaranteed to be available for the current
user to edit with.

## Extends

-   [`CharacterStylesInput`](CharacterStylesInput.md).[`StyleRange`](StyleRange.md)

## Properties

### color?

• `optional` **color**: [`Color`](Color.md)

Text color.

#### Inherited from

[`CharacterStylesInput`](CharacterStylesInput.md).[`color`](CharacterStylesInput.md#color)

---

### font?

• `optional` **font**: [`AvailableFont`](../classes/AvailableFont.md)

#### Inherited from

[`CharacterStylesInput`](CharacterStylesInput.md).[`font`](CharacterStylesInput.md#font)

---

### fontSize?

• `optional` **fontSize**: `number`

Size of the text in points.

#### Inherited from

[`CharacterStylesInput`](CharacterStylesInput.md).[`fontSize`](CharacterStylesInput.md#fontsize)

---

### length

• **length**: `number`

The length or number of characters in which character styles will be applied.
Note: since characters are represented as UTF-16 code units, some symbols
such as emojis are considered to have a length of 2.

#### Inherited from

[`StyleRange`](StyleRange.md).[`length`](StyleRange.md#length)

---

### letterSpacing?

• `optional` **letterSpacing**: `number`

Uniformly adjusts the letter spacing, aka character spacing. Specified as a delta relative to the font's default
spacing, in units of 1/1000 em: positive values increase the spacing, negative values tighten the spacing, and 0
leaves spacing at its default.

#### Inherited from

[`CharacterStylesInput`](CharacterStylesInput.md).[`letterSpacing`](CharacterStylesInput.md#letterspacing)

---

### underline?

• `optional` **underline**: `boolean`

Adds an underline to text.

#### Inherited from

[`CharacterStylesInput`](CharacterStylesInput.md).[`underline`](CharacterStylesInput.md#underline)
[@express-document-sdk](../overview.md) / Color

# Interface: Color

Represents an RGBA color value.

## Properties

### alpha

• **alpha**: `number`

The alpha channel in range from 0 - 1.

---

### blue

• **blue**: `number`

The blue channel in range from 0 - 1.

---

### green

• **green**: `number`

The green channel in range from 0 - 1.

---

### red

• **red**: `number`

The red channel in range from 0 - 1.
[@express-document-sdk](../overview.md) / ColorFill

# Interface: ColorFill

Represents a solid-color fill.

The most convenient way to create a fill is via `Editor.makeColorFill()`.

## Extends

-   [`Fill`](Fill.md)

## Properties

### color

• **color**: [`Color`](Color.md)

The fill color.

---

### type

• `readonly` **type**: [`color`](../enumerations/FillType.md#color)

The fill type.

#### Overrides

[`Fill`](Fill.md).[`type`](Fill.md#type)
[@express-document-sdk](../overview.md) / ContainerNode

# Interface: ContainerNode

Interface for any node that contains an entirely generic collection of children. Some ContainerNode classes may host
_additional_ children in other specific "slots," such as background or mask layers; and non-ContainerNode classes may
also hold children in specified "slots." Use [Node.allChildren](../classes/Node.md#allchildren) for read access to children regardless of node type.

Some ContainerNode classes may be full-fledged Node subclasses (such as Group), while others may be a subclass of the
more minimal VisualNode (such as Artboard).

## Extends

-   [`VisualNode`](../classes/VisualNode.md)

## Accessors

### addOnData

• `get` **addOnData**(): [`AddOnData`](../classes/AddOnData.md)

Get [AddOnData](../classes/AddOnData.md) reference for managing the private metadata on this node for this add-on.

#### Returns

[`AddOnData`](../classes/AddOnData.md)

---

### allChildren

• `get` **allChildren**(): `Readonly`<`Iterable`<[`BaseNode`](../classes/BaseNode.md), `any`, `any`\>\>

Returns a read-only list of all children of the node. General-purpose content containers such as ArtboardNode or
GroupNode also provide a mutable [ContainerNode.children](ContainerNode.md#children) list. Other nodes with a more specific structure can
hold children in various discrete "slots"; this `allChildren` list includes _all_ such children and reflects their
overall display z-order.

Although BaseNode's allChildren may yield other BaseNodes, the subclasses Node and ArtboardNode override allChildren
to guarantee all their children are full-fledged Node instances.

#### Returns

`Readonly`<`Iterable`<[`BaseNode`](../classes/BaseNode.md), `any`, `any`\>\>

---

### boundsLocal

• `get` **boundsLocal**(): `Readonly`<[`Rect`](Rect.md)\>

The bounding box of the node, expressed in the node's local coordinate space (which may be shifted or rotated
relative to its parent). Generally matches the selection outline seen in the UI, encompassing the vector path
"spine" of the shape as well as its stroke, but excluding effects such as shadows.

The top-left corner of the bounding box corresponds to the visual top-left corner of the node, but this value is
_not_ necessarily (0,0) – this is especially true for Text and Path nodes.

#### Returns

`Readonly`<[`Rect`](Rect.md)\>

---

### centerPointLocal

• `get` **centerPointLocal**(): `Readonly`<[`Point`](Point.md)\>

Position of the node's centerpoint in its own local coordinate space, i.e. the center of the boundsLocal box.

#### Returns

`Readonly`<[`Point`](Point.md)\>

---

### children

• `get` **children**(): [`ItemList`](../classes/ItemList.md)<[`Node`](../classes/Node.md)\>

The node's children. Use the methods on this ItemList object to get, add, and remove children.

#### Returns

[`ItemList`](../classes/ItemList.md)<[`Node`](../classes/Node.md)\>

---

### id

• `get` **id**(): `string`

A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is
moved to a different part of the document.

#### Returns

`string`

---

### parent

• `get` **parent**(): `undefined` \| [`BaseNode`](../classes/BaseNode.md)

The node's parent. The parent chain will eventually reach ExpressRootNode for all nodes that are part of the document
content.

Nodes that have been deleted are "orphaned," with a parent chain that terminates in `undefined` without reaching the
root node. Such nodes cannot be selected, so it is unlikely to encounter one unless you retain a reference to a node
that was part of the document content earlier. Deleted nodes can be reattached to the scenegraph, e.g. via Undo.

#### Returns

`undefined` \| [`BaseNode`](../classes/BaseNode.md)

---

### topLeftLocal

• `get` **topLeftLocal**(): `Readonly`<[`Point`](Point.md)\>

Position of the node's top-left corner in its own local coordinate space, equal to (boundsLocal.x,
boundsLocal.y). If the node is rotated, this is not the same as the top-left corner of
boundsInParent.

#### Returns

`Readonly`<[`Point`](Point.md)\>

---

### type

• `get` **type**(): [`SceneNodeType`](../enumerations/SceneNodeType.md)

The node's type.

#### Returns

[`SceneNodeType`](../enumerations/SceneNodeType.md)

---

### visualRoot

• `get` **visualRoot**(): [`VisualNode`](../classes/VisualNode.md)

The highest ancestor that still has visual presence in the document. Typically an Artboard, but for orphaned
content, it will be the root of the deleted content (which might be this node itself).

Nodes that are both in the same visualRoot subtree lie within the same "visual space" of the document's
structure. Nodes that are in different visual roots have no spatial relation to one another; there is no
meaningful comparison or conversion between the bounds or coordinate spaces of such nodes.

#### Returns

[`VisualNode`](../classes/VisualNode.md)

## Methods

### localPointInNode()

• **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](Point.md)\>

Convert a point given in the node’s local coordinate space to a point in the coordinate space of the target node.
Both nodes must share the same [visualRoot](../classes/VisualNode.md#visualroot), but can lie anywhere within that subtree relative to one
another (the target node need not be an ancestor of this node, nor vice versa).

#### Parameters

• **localPoint**: [`Point`](Point.md)

• **targetNode**: [`VisualNode`](../classes/VisualNode.md)

#### Returns

`Readonly`<[`Point`](Point.md)\>

#### Inherited from

[`VisualNode`](../classes/VisualNode.md).[`localPointInNode`](../classes/VisualNode.md#localpointinnode)

---

### removeFromParent()

• **removeFromParent**(): `void`

Removes the node from its parent - effectively deleting it, if the node is not re-added to another parent before the
document is closed.

If parent is a basic ContainerNode, this is equivalent to `node.parent.children.remove(node)`. For nodes with other
child "slots," removes the child from whichever slot it resides in, if possible. Throws if the slot does not permit
removal. No-op if node is already an orphan.

#### Returns

`void`

#### Inherited from

[`VisualNode`](../classes/VisualNode.md).[`removeFromParent`](../classes/VisualNode.md#removefromparent)
[@express-document-sdk](../overview.md) / Fill

# Interface: Fill

Base interface representing any fill in the scenegraph. See [FillableNode](../classes/FillableNode.md).
Currently, you can only create [ColorFill](ColorFill.md)s, but you might encounter
other fill types when reading scenegraph content.

## Extended by

-   [`ColorFill`](ColorFill.md)

## Properties

### type

• `readonly` **type**: [`color`](../enumerations/FillType.md#color)

The fill type.
[@express-document-sdk](../overview.md) / IFillableNode

# Interface: IFillableNode

Interface for [FillableNode](../classes/FillableNode.md) _and_ any other nodes with a similar `fill` property that do not directly inherit from
the FillableNode class.

## Properties

### fill

• **fill**: `undefined` \| [`Fill`](Fill.md)
[@express-document-sdk](../overview.md) / IRectangularNode

# Interface: IRectangularNode

Interface for nodes with width and height properties.

## Properties

### height

• **height**: `number`

---

### width

• **width**: `number`
[@express-document-sdk](../overview.md) / IStrokableNode

# Interface: IStrokableNode

Interface for [StrokableNode](../classes/StrokableNode.md) _and_ any other nodes with a similar `stroke` property that do not directly inherit
from the StrokableNode class. (See [ArtboardNode](../classes/ArtboardNode.md), for example).

## Properties

### stroke

• **stroke**: `undefined` \| [`Stroke`](Stroke.md)
[@express-document-sdk](../overview.md) / ListItem

# Interface: ListItem

Base interface for any item that can be used in [ItemList](../classes/ItemList.md). ItemList is used in different places to hold various
types of items, including Nodes, Fills, and Strokes.
[@express-document-sdk](../overview.md) / OrderedListStyleInput

# Interface: OrderedListStyleInput

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

Interface for specifying an ordered list style, such as a numbered list.

## Extends

-   `BaseParagraphListStyle`

## Properties

### indentLevel?

• `optional` **indentLevel**: `number`

A value from 0-8 that specifies indent/nesting level. Default is 0 if not provided.

#### Inherited from

`BaseParagraphListStyle.indentLevel`

---

### numbering?

• `optional` **numbering**: [`OrderedListNumbering`](../namespaces/Constants/enumerations/OrderedListNumbering.md)

The numbering style to use. If undefined, it defaults to a different type depending on the paragraph's indent level.
The defaults for increasing indent are 1, a, i, I, and then they repeat.
These markers and the prefix/postfix strings (if any) are displayed using the same font as the start of the
paragraph's text content.

---

### postfix?

• `optional` **postfix**: `string`

Additional string to display after each sequence number/letter, e.g. ")" or "."

---

### prefix?

• `optional` **prefix**: `string`

Additional string to display before each sequence number/letter, e.g. "("

---

### type

• **type**: [`ordered`](../namespaces/Constants/enumerations/ParagraphListType.md#ordered)
[@express-document-sdk](../overview.md) / ParagraphStyles

# Interface: ParagraphStyles

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

Text styles that must be applied to an entire paragraph atomically. (Contrast with CharacterStyles which can be applied to
any range of characters, even a short span like one single word).

## Extends

-   [`BaseParagraphStyles`](BaseParagraphStyles.md)

## Extended by

-   [`ParagraphStylesRange`](ParagraphStylesRange.md)

## Properties

### lineSpacing

• **lineSpacing**: `number`

Spacing between lines, aka leading, expressed as a multiple of the font size's default spacing - ex. 1.5 = 150% of normal.
It only affects the space *between* lines, not the space above the first line or below the last line.

#### Inherited from

[`BaseParagraphStyles`](BaseParagraphStyles.md).[`lineSpacing`](BaseParagraphStyles.md#linespacing)

---

### list?

• `optional` **list**: `Required`<[`OrderedListStyleInput`](OrderedListStyleInput.md)\> \| `Required`<[`UnorderedListStyleInput`](UnorderedListStyleInput.md)\>

---

### spaceAfter

• **spaceAfter**: `number`

Space after paragraph (in points). It does not affect the last paragraph. It is additive to the next paragraph's spaceBefore
(adjacent spacing does not merge/collapse together).

#### Inherited from

[`BaseParagraphStyles`](BaseParagraphStyles.md).[`spaceAfter`](BaseParagraphStyles.md#spaceafter)

---

### spaceBefore

• **spaceBefore**: `number`

Space before paragraph (in points). It does not affect the first paragraph. It is additive to previous paragraph's spaceAfter
(adjacent spacing does not merge/collapse together).

#### Inherited from

[`BaseParagraphStyles`](BaseParagraphStyles.md).[`spaceBefore`](BaseParagraphStyles.md#spacebefore)
[@express-document-sdk](../overview.md) / ParagraphStylesInput

# Interface: ParagraphStylesInput

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

The variant of [ParagraphStyles](ParagraphStyles.md) with all optional style fields is used to apply ParagraphStyles(). When using that API,
any fields not specified are left unchanged, preserving the text's existing styles.

## Extends

-   `Partial`<[`BaseParagraphStyles`](BaseParagraphStyles.md)\>

## Extended by

-   [`ParagraphStylesRangeInput`](ParagraphStylesRangeInput.md)

## Properties

### lineSpacing?

• `optional` **lineSpacing**: `number`

Spacing between lines, aka leading, expressed as a multiple of the font size's default spacing - ex. 1.5 = 150% of normal.
It only affects the space *between* lines, not the space above the first line or below the last line.

#### Inherited from

`Partial.lineSpacing`

---

### list?

• `optional` **list**: [`OrderedListStyleInput`](OrderedListStyleInput.md) \| [`UnorderedListStyleInput`](UnorderedListStyleInput.md)

---

### spaceAfter?

• `optional` **spaceAfter**: `number`

Space after paragraph (in points). It does not affect the last paragraph. It is additive to the next paragraph's spaceBefore
(adjacent spacing does not merge/collapse together).

#### Inherited from

`Partial.spaceAfter`

---

### spaceBefore?

• `optional` **spaceBefore**: `number`

Space before paragraph (in points). It does not affect the first paragraph. It is additive to previous paragraph's spaceAfter
(adjacent spacing does not merge/collapse together).

#### Inherited from

`Partial.spaceBefore`
[@express-document-sdk](../overview.md) / ParagraphStylesRange

# Interface: ParagraphStylesRange

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

A set of [ParagraphStyles](ParagraphStyles.md) and the text range they apply to. It is seen in the paragraphStyleRanges getter.

## Extends

-   [`ParagraphStyles`](ParagraphStyles.md).[`StyleRange`](StyleRange.md)

## Properties

### length

• **length**: `number`

The length or number of characters in which character styles will be applied.
Note: since characters are represented as UTF-16 code units, some symbols
such as emojis are considered to have a length of 2.

#### Inherited from

[`StyleRange`](StyleRange.md).[`length`](StyleRange.md#length)

---

### lineSpacing

• **lineSpacing**: `number`

Spacing between lines, aka leading, expressed as a multiple of the font size's default spacing - ex. 1.5 = 150% of normal.
It only affects the space *between* lines, not the space above the first line or below the last line.

#### Inherited from

[`ParagraphStyles`](ParagraphStyles.md).[`lineSpacing`](ParagraphStyles.md#linespacing)

---

### list?

• `optional` **list**: `Required`<[`OrderedListStyleInput`](OrderedListStyleInput.md)\> \| `Required`<[`UnorderedListStyleInput`](UnorderedListStyleInput.md)\>

#### Inherited from

[`ParagraphStyles`](ParagraphStyles.md).[`list`](ParagraphStyles.md#list)

---

### spaceAfter

• **spaceAfter**: `number`

Space after paragraph (in points). It does not affect the last paragraph. It is additive to the next paragraph's spaceBefore
(adjacent spacing does not merge/collapse together).

#### Inherited from

[`ParagraphStyles`](ParagraphStyles.md).[`spaceAfter`](ParagraphStyles.md#spaceafter)

---

### spaceBefore

• **spaceBefore**: `number`

Space before paragraph (in points). It does not affect the first paragraph. It is additive to previous paragraph's spaceAfter
(adjacent spacing does not merge/collapse together).

#### Inherited from

[`ParagraphStyles`](ParagraphStyles.md).[`spaceBefore`](ParagraphStyles.md#spacebefore)
[@express-document-sdk](../overview.md) / ParagraphStylesRangeInput

# Interface: ParagraphStylesRangeInput

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

A variant of [ParagraphStylesRange](ParagraphStylesRange.md) with all style fields optional and the text range they apply to. Used for the
paragraphStyleRanges setter. When invoking the setter, any fields not specified are reset to their defaults.

Paragraphs are separated by newline characters (`\n`). The ranges specified here should align with
those boundaries.

## Extends

-   [`ParagraphStylesInput`](ParagraphStylesInput.md).[`StyleRange`](StyleRange.md)

## Properties

### length

• **length**: `number`

The length or number of characters in which character styles will be applied.
Note: since characters are represented as UTF-16 code units, some symbols
such as emojis are considered to have a length of 2.

#### Inherited from

[`StyleRange`](StyleRange.md).[`length`](StyleRange.md#length)

---

### lineSpacing?

• `optional` **lineSpacing**: `number`

Spacing between lines, aka leading, expressed as a multiple of the font size's default spacing - ex. 1.5 = 150% of normal.
It only affects the space *between* lines, not the space above the first line or below the last line.

#### Inherited from

[`ParagraphStylesInput`](ParagraphStylesInput.md).[`lineSpacing`](ParagraphStylesInput.md#linespacing)

---

### list?

• `optional` **list**: [`OrderedListStyleInput`](OrderedListStyleInput.md) \| [`UnorderedListStyleInput`](UnorderedListStyleInput.md)

#### Inherited from

[`ParagraphStylesInput`](ParagraphStylesInput.md).[`list`](ParagraphStylesInput.md#list)

---

### spaceAfter?

• `optional` **spaceAfter**: `number`

Space after paragraph (in points). It does not affect the last paragraph. It is additive to the next paragraph's spaceBefore
(adjacent spacing does not merge/collapse together).

#### Inherited from

[`ParagraphStylesInput`](ParagraphStylesInput.md).[`spaceAfter`](ParagraphStylesInput.md#spaceafter)

---

### spaceBefore?

• `optional` **spaceBefore**: `number`

Space before paragraph (in points). It does not affect the first paragraph. It is additive to previous paragraph's spaceAfter
(adjacent spacing does not merge/collapse together).

#### Inherited from

[`ParagraphStylesInput`](ParagraphStylesInput.md).[`spaceBefore`](ParagraphStylesInput.md#spacebefore)
[@express-document-sdk](../overview.md) / Point

# Interface: Point

Represents a 2D position.

## Properties

### x

• **x**: `number`

---

### y

• **y**: `number`
[@express-document-sdk](../overview.md) / PointTextLayout

# Interface: PointTextLayout

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

## Properties

### type

• **type**: [`autoWidth`](../enumerations/TextType.md#autowidth)
[@express-document-sdk](../overview.md) / Rect

# Interface: Rect

## Properties

### height

• **height**: `number`

---

### width

• **width**: `number`

---

### x

• **x**: `number`

---

### y

• **y**: `number`
[@express-document-sdk](../overview.md) / RectangleGeometry

# Interface: RectangleGeometry

## Properties

### height

• **height**: `number`

---

### width

• **width**: `number`
[@express-document-sdk](../overview.md) / SolidColorStroke

# Interface: SolidColorStroke

Represents a solid-color stroke, with optional dashes.

The most convenient way to create a solid-color stroke is via `Editor.makeStroke()`. This also futureproofs
your code in case any other required fields are added to the Stroke descriptor in the future.

## Extends

-   [`Stroke`](Stroke.md)

## Properties

### color

• **color**: [`Color`](Color.md)

The color of a stroke.

---

### dashOffset

• **dashOffset**: `number`

Number of pixels the beginning of dash pattern should be offset along the stroke.

---

### dashPattern

• **dashPattern**: `number`[]

If empty, this is a solid stroke.
If non-empty, the values alternate between length of a rendered and blank segment,
repeated along the length of the stroke. The first value represents the first solid segment.
Array must be of even length. Values cannot be negative.

---

### position

• **position**: [`StrokePosition`](../enumerations/StrokePosition.md)

The position of the stroke relative to the outline of the shape.

---

### type

• `readonly` **type**: [`color`](../enumerations/StrokeType.md#color)

The stroke type.

#### Overrides

[`Stroke`](Stroke.md).[`type`](Stroke.md#type)

---

### width

• **width**: `number`

The thickness of a stroke. Must be from MIN_STROKE_WIDTH to MAX_STROKE_WIDTH.
[@express-document-sdk](../overview.md) / Stroke

# Interface: Stroke

Base interface representing any stroke in the scenegraph. See [StrokableNode](../classes/StrokableNode.md).
Currently, you can only create [SolidColorStroke](SolidColorStroke.md)s, but you might encounter
other stroke types when reading from scenegraph content.

## Extended by

-   [`SolidColorStroke`](SolidColorStroke.md)

## Properties

### type

• `readonly` **type**: [`color`](../enumerations/StrokeType.md#color)
[@express-document-sdk](../overview.md) / StyleRange

# Interface: StyleRange

Represents a range of characters defined by a length (and implicitly started at the end of the previous range).

## Extended by

-   [`CharacterStylesRangeInput`](CharacterStylesRangeInput.md)
-   [`CharacterStylesRange`](CharacterStylesRange.md)
-   [`ParagraphStylesRangeInput`](ParagraphStylesRangeInput.md)
-   [`ParagraphStylesRange`](ParagraphStylesRange.md)

## Properties

### length

• **length**: `number`

The length or number of characters in which character styles will be applied.
Note: since characters are represented as UTF-16 code units, some symbols
such as emojis are considered to have a length of 2.
[@express-document-sdk](../overview.md) / TextRange

# Interface: TextRange

A range of text in a [TextContentModel](../classes/TextContentModel.md).

## Properties

### length

• **length**: `number`

---

### start

• **start**: `number`
[@express-document-sdk](../overview.md) / UnorderedListStyleInput

# Interface: UnorderedListStyleInput

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

Interface for specifying an unordered list style, such as a bullet list.

## Extends

-   `BaseParagraphListStyle`

## Properties

### indentLevel?

• `optional` **indentLevel**: `number`

A value from 0-8 that specifies indent/nesting level. Default is 0 if not provided.

#### Inherited from

`BaseParagraphListStyle.indentLevel`

---

### marker?

• `optional` **marker**: `string`

Marker symbol to use. If undefined, it defaults to a different symbol depending on the paragraph's indent level.
The defaults for increasing indent are: •, ◦, ◼, ◻, and then they repeat.
Markers are always displayed using the default font (SourceSans3 Regular), regardless of the font(s) used in the
paragraph's text content. A default marker is used instead if the default font does not support the symbol.

Text or Unicode glyphs are accepted to represent the list marker.

---

### type

• **type**: [`unordered`](../namespaces/Constants/enumerations/ParagraphListType.md#unordered)
[@express-document-sdk](../overview.md) / UnsupportedTextLayout

# Interface: UnsupportedTextLayout

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

## Properties

### type

• **type**: [`magicFit`](../enumerations/TextType.md#magicfit) \| [`circular`](../enumerations/TextType.md#circular)
[@express-document-sdk](../../../overview.md) / [Constants](../overview.md) / OrderedListNumbering

# Enumeration: OrderedListNumbering

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../../../manifest/index.md#requirements) section of the `manifest.json`.

Numbering types used to display ordered lists: 1, A, a, I, i 01, 001.

## Enumeration Members

### doubleZeroPrefixNumeric

• **doubleZeroPrefixNumeric**: `8`

---

### lowercaseAlpha

• **lowercaseAlpha**: `3`

---

### lowercaseRomanNum

• **lowercaseRomanNum**: `5`

---

### numeric

• **numeric**: `1`

---

### singleZeroPrefixNumeric

• **singleZeroPrefixNumeric**: `7`

---

### uppercaseAlpha

• **uppercaseAlpha**: `2`

---

### uppercaseRomanNum

• **uppercaseRomanNum**: `4`
[@express-document-sdk](../../../overview.md) / [Constants](../overview.md) / ParagraphListType

# Enumeration: ParagraphListType

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../../../manifest/index.md#requirements) section of the `manifest.json`.

Indicates list type: see [UnorderedListStyleInput](../../../interfaces/UnorderedListStyleInput.md) and [OrderedListStyleInput](../../../interfaces/OrderedListStyleInput.md).

## Enumeration Members

### ordered

• **ordered**: `1`

---

### unordered

• **unordered**: `0`
[**@express-document-sdk**](../../overview.md) • **Docs**

---

[@express-document-sdk](../../overview.md) / Constants

# Namespace: Constants

## Index

### Enumerations

- [OrderedListNumbering](enumerations/OrderedListNumbering.md)
- [ParagraphListType](enumerations/ParagraphListType.md)

## References

### ArrowHeadType

Re-exports [ArrowHeadType](../../enumerations/ArrowHeadType.md)

---

### BlendMode

Re-exports [BlendMode](../../enumerations/BlendMode.md)

---

### EditorEvent

Re-exports [EditorEvent](../../enumerations/EditorEvent.md)

---

### FillRule

Re-exports [FillRule](../../enumerations/FillRule.md)

---

### FillType

Re-exports [FillType](../../enumerations/FillType.md)

---

### SceneNodeType

Re-exports [SceneNodeType](../../enumerations/SceneNodeType.md)

---

### StrokePosition

Re-exports [StrokePosition](../../enumerations/StrokePosition.md)

---

### StrokeType

Re-exports [StrokeType](../../enumerations/StrokeType.md)

---

### TextAlignment

Re-exports [TextAlignment](../../enumerations/TextAlignment.md)

---

### TextType

Re-exports [TextType](../../enumerations/TextType.md)

---

### VisualEffectType

Re-exports [VisualEffectType](../../enumerations/VisualEffectType.md)
**@express-document-sdk** • **Docs**

---

# @express-document-sdk

## Namespaces

-   [Constants](namespaces/Constants/overview.md)

## Enumerations

-   [ArrowHeadType](enumerations/ArrowHeadType.md)
-   [BlendMode](enumerations/BlendMode.md)
-   [EditorEvent](enumerations/EditorEvent.md)
-   [FillRule](enumerations/FillRule.md)
-   [FillType](enumerations/FillType.md)
-   [SceneNodeType](enumerations/SceneNodeType.md)
-   [StrokePosition](enumerations/StrokePosition.md)
-   [StrokeType](enumerations/StrokeType.md)
-   [TextAlignment](enumerations/TextAlignment.md)
-   [TextType](enumerations/TextType.md)
-   [VisualEffectType](enumerations/VisualEffectType.md)

## Classes

-   [AddOnData](classes/AddOnData.md)
-   [ArtboardList](classes/ArtboardList.md)
-   [ArtboardNode](classes/ArtboardNode.md)
-   [AvailableFont](classes/AvailableFont.md)
-   [BaseFont](classes/BaseFont.md)
-   [BaseNode](classes/BaseNode.md)
-   [ColorUtils](classes/ColorUtils.md)
-   [ComplexShapeNode](classes/ComplexShapeNode.md)
-   [Context](classes/Context.md)
-   [Editor](classes/Editor.md)
-   [EllipseNode](classes/EllipseNode.md)
-   [ExpressRootNode](classes/ExpressRootNode.md)
-   [FillableNode](classes/FillableNode.md)
-   [Fonts](classes/Fonts.md)
-   [GridCellNode](classes/GridCellNode.md)
-   [GridLayoutNode](classes/GridLayoutNode.md)
-   [GroupNode](classes/GroupNode.md)
-   [ImageRectangleNode](classes/ImageRectangleNode.md)
-   [ItemList](classes/ItemList.md)
-   [LineNode](classes/LineNode.md)
-   [MediaContainerNode](classes/MediaContainerNode.md)
-   [Node](classes/Node.md)
-   [PageList](classes/PageList.md)
-   [PageNode](classes/PageNode.md)
-   [PathNode](classes/PathNode.md)
-   [ReadOnlyItemList](classes/ReadOnlyItemList.md)
-   [RectangleNode](classes/RectangleNode.md)
-   [RestrictedItemList](classes/RestrictedItemList.md)
-   [SolidColorShapeNode](classes/SolidColorShapeNode.md)
-   [StrokableNode](classes/StrokableNode.md)
-   [StrokeShapeNode](classes/StrokeShapeNode.md)
-   [TextContentModel](classes/TextContentModel.md)
-   [TextNode](classes/TextNode.md)
-   [UnavailableFont](classes/UnavailableFont.md)
-   [UnknownNode](classes/UnknownNode.md)
-   [Viewport](classes/Viewport.md)
-   [VisualNode](classes/VisualNode.md)

## Interfaces

-   [AreaTextLayout](interfaces/AreaTextLayout.md)
-   [AutoHeightTextLayout](interfaces/AutoHeightTextLayout.md)
-   [BaseParagraphStyles](interfaces/BaseParagraphStyles.md)
-   [BitmapImage](interfaces/BitmapImage.md)
-   [CharacterStyles](interfaces/CharacterStyles.md)
-   [CharacterStylesInput](interfaces/CharacterStylesInput.md)
-   [CharacterStylesRange](interfaces/CharacterStylesRange.md)
-   [CharacterStylesRangeInput](interfaces/CharacterStylesRangeInput.md)
-   [Color](interfaces/Color.md)
-   [ColorFill](interfaces/ColorFill.md)
-   [ContainerNode](interfaces/ContainerNode.md)
-   [Fill](interfaces/Fill.md)
-   [IFillableNode](interfaces/IFillableNode.md)
-   [IRectangularNode](interfaces/IRectangularNode.md)
-   [IStrokableNode](interfaces/IStrokableNode.md)
-   [ListItem](interfaces/ListItem.md)
-   [OrderedListStyleInput](interfaces/OrderedListStyleInput.md)
-   [ParagraphStyles](interfaces/ParagraphStyles.md)
-   [ParagraphStylesInput](interfaces/ParagraphStylesInput.md)
-   [ParagraphStylesRange](interfaces/ParagraphStylesRange.md)
-   [ParagraphStylesRangeInput](interfaces/ParagraphStylesRangeInput.md)
-   [Point](interfaces/Point.md)
-   [PointTextLayout](interfaces/PointTextLayout.md)
-   [Rect](interfaces/Rect.md)
-   [RectangleGeometry](interfaces/RectangleGeometry.md)
-   [SolidColorStroke](interfaces/SolidColorStroke.md)
-   [Stroke](interfaces/Stroke.md)
-   [StyleRange](interfaces/StyleRange.md)
-   [TextRange](interfaces/TextRange.md)
-   [UnorderedListStyleInput](interfaces/UnorderedListStyleInput.md)
-   [UnsupportedTextLayout](interfaces/UnsupportedTextLayout.md)

## Type Aliases

-   [EditorEventHandler](type-aliases/EditorEventHandler.md)
-   [EventHandlerId](type-aliases/EventHandlerId.md)
-   [Font](type-aliases/Font.md)
-   [OrderedListStyle](type-aliases/OrderedListStyle.md)
-   [SolidColorStrokeWithOptionalType](type-aliases/SolidColorStrokeWithOptionalType.md)
-   [UnorderedListStyle](type-aliases/UnorderedListStyle.md)

## References

### OrderedListNumbering

Re-exports [OrderedListNumbering](namespaces/Constants/enumerations/OrderedListNumbering.md)

---

### ParagraphListType

Re-exports [ParagraphListType](namespaces/Constants/enumerations/ParagraphListType.md)
[@express-document-sdk](../overview.md) / EditorEventHandler

# Type alias: EditorEventHandler()

• **EditorEventHandler**: () => `void`

This type represents function signature for the editor event handler callback.

## Returns

`void`
[@express-document-sdk](../overview.md) / EventHandlerId

# Type alias: EventHandlerId

• **EventHandlerId**: `string`

This type represents unique id of each event handler callback that is registered.
[@express-document-sdk](../overview.md) / Font

# Type alias: Font

• **Font**: [`AvailableFont`](../classes/AvailableFont.md) \| [`UnavailableFont`](../classes/UnavailableFont.md)

Represents a font in the document.

Note: not every font encountered in the existing content is available for editing.
Check the `availableForEditing` property to be sure.
[@express-document-sdk](../overview.md) / OrderedListStyle

# Type alias: OrderedListStyle

• **OrderedListStyle**: `Required`<[`OrderedListStyleInput`](../interfaces/OrderedListStyleInput.md)\>

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

OrderedListStyle represents the style of an ordered list.
[@express-document-sdk](../overview.md) / SolidColorStrokeWithOptionalType

# Type alias: SolidColorStrokeWithOptionalType

• **SolidColorStrokeWithOptionalType**: `Omit`<[`SolidColorStroke`](../interfaces/SolidColorStroke.md), `"type"`\> & `Partial`<`Pick`<[`SolidColorStroke`](../interfaces/SolidColorStroke.md), `"type"`\>\>

SolidColorStroke with 'type' property as optional.
[@express-document-sdk](../overview.md) / UnorderedListStyle

# Type alias: UnorderedListStyle

• **UnorderedListStyle**: `Required`<[`UnorderedListStyleInput`](../interfaces/UnorderedListStyleInput.md)\>

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.

UnorderedListStyle represents the style of an unordered list.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: Document Sandbox Overview
description: An overview of the document sandbox used for content authoring with the Adobe Express Document APIs.
contributors:
  - https://github.com/hollyschinsky
---

# Document Sandbox

The document sandbox is a sandboxed JavaScript execution environment, which allows to execute add-on's JavaScript code securely and synchronously in another JavaScript environment e.g., browser.

## Overview

The document sandbox exposes three categories of APIs, which each have their own specific references and are outlined below.

### Communication APIs

The [communication APIs](./communication/index.md) allow you to communicate between the document sandbox and the iframe runtime where your add-on is running via exposed APIs.

### Web APIs

The document sandbox does NOT provide a full fledged browser’s JavaScript execution environment. Most of the browsers APIs/Global Objects are not available. For these, the developers can use iframe runtime environment and [communicate](./communication/index.md#expose-apis-from-the-ui) the result back to the script running inside document sandbox environment. Some of the commonly used [Web APIs](./web/index.md) (with limited scope) have been provided inside document sandbox environment.

### Document APIs

The [document APIs](./document-apis/) provide access to the user's document structure and properties, and allow you to make changes and author content to the Adobe Express document via the provided APIs.

<InlineAlert slots="text" variant="success"/>

Please see the [tutorials section](../../guides/tutorials/) to learn more about using the document sandbox and Adobe Express Document APIs.

## Document Sandbox's JavaScript Engine

The document sandbox is a sandboxed JavaScript execution environment, which allows to execute add-on's JavaScript code securely and synchronously in another JavaScript environment e.g., browser.

Some key concepts to note about the document sandbox include:

- Limited access to browser APIs (see the [Web APIs](./web/index.md) reference). Note however, you can use the [communication APIs](./communication/index.md) to expose browser APIs (ie: `fetch`) from the iframe environment to be used in the document sandbox.
- Runs in a slower execution environment.
- Provides no debugging capabilities other than those provided by the [injected `console` functions](./web/index.md#console-object).
- Runs in the same context/thread as the host's application business logic, thus providing access to interact with it via the injected APIs.

## Getting Started with the APIs

The methods defined in the [communication API reference](./communication/) are used to expose and use the API proxies between the iframe and script environments of your add-on. Start with the [communication reference](./communication/) to learn more about how to expose APIs and use them from either environment.

### Document sandbox entry point

To use the document sandbox APIs in your add-on, start by defining a new `documentSandbox` entry point in your `manifest.json` file with the value set to the name of the file containing the JavaScript code you're using with the document sandbox APIs:

```json
    "entryPoints": [
        {
            "type": "panel",
            "id": "panel1",
            "main": "index.html",
            "documentSandbox": "code.js"
        }
    ]
```

The JavaScript code in the file referenced can then access any of the injected global objects and module APIs defined in all of the APIs outlined in this set of references ([communication APIs](./communication/), [Web APIs](./web/) and [document APIs](./document-apis/)).

### CLI Generated Document Sandbox Add-on

The quickest way to get started with a scaffolded project set up with the document sandbox bindings for you is via the CLI. When creating a new add-on, you can [specify a template name](../../guides/getting_started/dev_tooling.md#templates) that includes the document sandbox support:

`npx @adobe/create-ccweb-add-on helloworld --template javascript-with-document-sandbox`

 or the CLI will prompt you to choose from the [base templates](../../guides/getting_started/dev_tooling.md#templates), then ask if you want to include the document sandbox:

![CLI prompt for document sandbox](../img/cli-doc-sandbox-prompt.png)

Choose `Yes` at the prompt to include the document sandbox setup in your generated project. The project structure that's generated will differ depending on which base template you chose, but the two important additions to note, are the existence of a `script` entry point in your `manifest.json`, and the `code.js` file it references.

```json
"entryPoints": [
        {
            "type": "panel",
            "id": "panel1",
            "main": "index.html",
            "documentSandbox": "code.js"
        }
    ]
```

The screenshot below shows what the default script-based add-on generated from the CLI looks like when running:

![script add-on sample screenshot](../img/script-add-on-sample.png)

<InlineAlert slots="text" variant="info"/>

Please refer to the [Using the CLI](../../guides/getting_started/dev_tooling.md#using-the-cli) section to get more information on how to use the CLI and create new add-on.
<br/>

## Code Samples

The following [code samples](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples) have also been provided to help you get started using these new document sandbox APIs.

### [communication-iframe-documentSandbox sample](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/communication-iframe-documentSandbox)

Demonstrates the use of the communication APIs to expose and proxy APIs bidirectionally between the iframe and document sandbox environments. Also includes demonstrating how to use some of the [Web APIs](./web/) such as `console.log()`.

### [editor-apis sample](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/editor-apis)

Demonstrates how to use the [document APIs](./document-apis/) to create various shapes and add them to the document.

### [image-and-page sample](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/image-and-page)

A more comprehensive example of using the [document APIs](./document-apis/) to add a page, images and shapes, as well as clear the artboard.

## Debugging script based add-ons

Debugging with breakpoints from the document sandbox (via `code.js`) is currently not supported and for the time-being, only console logging (via `console.log()`) can be used. However, support for debugging by applying breakpoints in the code will be available in the near future. Please refer to [Example Code Snippet](./document-apis/index.md#example-code-snippet), where a `rectangle` object is printed to console for debugging purpose.
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: Web APIs
description: An overview of the Web APIs available as part of the document sandbox.
contributors:
  - https://github.com/hollyschinsky
---

# Web APIs

The Web APIs refer to the set of commonly used APIs that are injected by the document sandbox into the global context to allow you to access common JavaScript functions.

## Overview

The document sandbox runtime provides implementations of some common Web APIs to perform tasks like logging to the console. They are limited to a set of basic functions currently, as outlined in the next section. Most of the browser's usual APIs/Global Objects are not available in the document sandbox. You can invoke other browser APIs using the iframe runtime environment and [communicate](../communication/index.md#expose-apis-from-the-ui) the result back to your code running inside the sandbox runtime.

<InlineAlert slots="text" variant="success"/>

These APIs can automatically be used in your document sandbox code.

## Console Object

A global [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console) object implementation is provided with the following JavaScript method implementations for use in your script code.

### console.log()

For general output of logging information. You may use string substitution and additional arguments with this method.

### console.info()

Informative logging of information. You may use string substitution and additional arguments with this method.

### console.warn()

Outputs a warning message. You may use string substitution and additional arguments with this method.

### console.error()

Outputs an error message. You may use string substitution and additional arguments with this method.

### console.debug()

Outputs a message to the console with the log level debug.

### console.clear()

Clear the console.

### console.assert()

Log a message and stack trace to console if the first argument is false.
# Overview

Here you will find all of the technical references you'll need to help you throughout your add-on development.

## Add-on UI SDK Reference

A [traversable developer reference](./addonsdk/) for the add-on SDK where you will find detailed information about all of the objects, methods, properties and events you'll need for developing add-ons.

## Document Sandbox Reference

The [document sandbox](./document-sandbox/) is a sandboxed JavaScript execution environment, which allows to execute add-on's JavaScript code securely and synchronously in another JavaScript environment e.g., browser.

## Manifest Schema Reference

The add-on `manifest.json` file defines the metadata for your add-on and how it should behave. Use the [manifest schema reference](./manifest/) to discover all of the possible keys and values available for describing your add-on.

## Changelog

Visit the [Changelog](./changelog.md) to learn about all of the latest new features, updates, bug fixes and more!
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: Manifest Version 2
description: This is the manifest version 2 page
contributors:
  - https://github.com/hollyschinsky
---

# Manifest Schema Reference

## Introduction

Each add-on bundle contains a `manifest.json` file at the root level which defines the metadata for your add-on and how it should behave. This guide outlines the latest manifest version available, which is version 2.

### Sample manifest.json

```json
{
    "testId": "addon-sample",
    "name": "Add-on Sample",
    "version": "1.0.0",
    "manifestVersion": 2,
    "requirements": {
        "apps": [
            {
                "name": "Express",
                "apiVersion": 1
            }
        ],        
        "supportsTouch": false,
    },
    "entryPoints": [
        {
            "type": "panel",
            "id": "panel1",
            "main": "index.html",
            "documentSandbox": "code.js",
            "permissions": {
                "sandbox": ["allow-popups", "allow-presentation", "allow-downloads"],
                "oauth": ["www.dropbox.com"]
            }
        }
    ]
}
```

## Manifest Properties

**Note:** The **?** denotes the key is optional.

| Key         | Type         | Description   |
| -------------| -------------| -----------:  |
| `testId?`     | `string`     | Used to uniquely identify an add-on among other add-ons during a **development workflows only**. This is auto-generated and inserted into the manifest by the CLI when an add-on is created. This is mandatory in the development workflow and ignored in add-ons submitted to the marketplace. |
| `name?`     | `string`     | Add-on name **for development workflow only**. The name provided in the UI during submission is used in all other workflows. |
| `version`     | `string`     | Add-on version in "major.minor.patch" format (e.g. "1.2.0") |
| `manifestVersion`     | `number`     | Version of the manifest schema (e.g. 2).    |
| [`requirements`](#requirements)     | `object`     | Specify the apps the add-on is applicable for. |
| [`entryPoints`](#entrypoints)     | `object []`     | An entry point for your add-on. **At least one is required.** |

## requirements

| Key               | Type         | Description   |
| -------------------| -------------| -----------:  |
| [`apps`](#requirementsapps)    | `object []`  | Add-on authors can specify the apps that the add-on is intended for. |
| `experimentalApis?`| `boolean`    | Add-ons can opt to use experimental apis by specifying this flag. This flag is **only allowed during development** and needs to be removed during submission.                               |
| `supportsTouch?`   | `boolean`    | Whether the add-on supports touch-only devices. If not specified, the default value assumed is `false`.  |
| `renditionPreview?` | `boolean` |	Ensure premium content preview is properly handled for free users when add-ons create renditions. |

**Example:**<br/>

```json
"requirements": {
    "apps": [  
    {  
        "name": "Express", 
        "apiVersion": 1,
        "supportedDeviceClass": ["desktop"]
    }, 
    {…}],
    "experimentalApis": true,
    "supportsTouch": false,
    "renditionPreview": true
} 
```

### requirements.apps

| Key               | Type         | Description   |
| -------------------| -------------| -----------:  |
| `name`             | `string`       | Currently supported values: `"Express"` |
| `apiVersion`         | `number`       | API version that the add-on uses. Currently supported values: 1 |
| [`supportedDeviceClass?`](#requirementsappssupporteddeviceclass ) | `string []`  | Supported platforms by the add-on. If not specified, the default value assumed is: `["desktop"]`. |

<!-- | `supportedDeviceClass?` | `string []`  | Supported platforms by the add-on. Possible values are <ul><li>"desktop"</li><li>"mobile</li><li>"app"</li></ul> If not specified, default value assumed is: \["desktop"\]. | -->
**Example:**<br/>

```json
"apps": [
    {
        "name": "Express",
        "apiVersion": 1,
        "supportedDeviceClass": ["desktop"]
    }
],
```

#### requirements.apps.supportedDeviceClass

The following platform value is currently supported in the `supportedDeviceClass` key.

| Platform       | Description |
| ----------------| -------------|
| `desktop`       | Browser on desktop. |
<!-- Extra comment, otherwise the table will show the content anyway—bar the first cell -->
<!-- | `mobile`        | Browser on mobile and tablet devices. | -->
<!-- | `app`           | Native app on mobile and tablet devices. | -->

## entryPoints

| Key         | Type         | Description   |
| -------------| -------------| -----------:  |
| `type`       | `string`     | The type of the entry point. Currently supported values: `"panel"`.    |
| `id`         | `string`     | Identifier for the entry point. Must be unique within the add-on.  |
| `main`        | `string`    | Main file for this entry point when launched.   |
| `documentSandbox`      | `string`    | File containing the JavaScript code to use with the [document sandbox SDK and Adobe Express Document APIs](../document-sandbox/). |
| [`permissions`](#entrypointspermissions) | `object`    | The permissions defined for this entry point. |

**Example:**<br/>

```json
"entryPoints": [
    {
        "type": "panel",
        "id": "panel1",
        "main": "index.html",
        "permissions": {
            "sandbox": ["allow-popups", "allow-popups-to-escape-sandbox", "allow-presentation", "allow-downloads"],
            "oauth": ["www.dropbox.com"]
        }
    }
]
```

### entrypoints.permissions

| Key                   | Type         | Description   |
| -----------------------| -------------| -----------:  |
| [`sandbox?`](#entrypointspermissionssandbox) | `string []`  | List of iframe sandbox permissions.  |
| `oauth?`               | `string []` | List of 3rd party auth server domains for which OAuth workflow may be requested. |
| `clipboard?`  | `string []` | The allowed values for the list of clipboard permissions. Currently, `clipboard-write` is supported and allows an add-on to write arbitrary data to the clipboard. |
| `microphone?` | `string` | The [allowlists](https://developer.mozilla.org/en-US/docs/Web/HTTP/Permissions_Policy#allowlists) value used in iframe `‘allow’` attribute. Enables the add-on to access the user's microphone for audio input. |
| `camera?` | `string` | The [allowlists](https://developer.mozilla.org/en-US/docs/Web/HTTP/Permissions_Policy#allowlists) value used in iframe `‘allow’` attribute. Enables the add-on to access the user's camera for video input. |

**Example:**<br/>

```json
"permissions" : {
    "sandbox": [" allow-popups ", "allow-downloads"],
    "oauth" : ["...", "..."], 
    "clipboard": ["clipboard-write"],
    "microphone": "*", 
    "camera" : "*"
}
```

#### entrypoints.permissions.sandbox

The following permission values are currently supported in the `sandbox` key.

| Permission      |  Description |
| ----------------| -------------|
| `allow-popups`  |  Allows popups (such as `window.open()`, `target="_blank"`, or `showModalDialog()`). **Note: If this permission is not set and you're using popups, the popup will silently fail to open.** |
| `allow-popups-to-escape-sandbox` | Allows a sandboxed document to open new windows without forcing the sandboxing flags upon them |
| `allow-presentation`  | Lets the add-on start a [presentation session](https://developer.mozilla.org/en-US/docs/Web/API/PresentationRequest). |
| `allow-downloads`     | Allows downloading files through an &lt;a&gt; or &lt;area&gt; element with the download attribute, as well as through the navigation that leads to a download of a file.          |

**Example:**<br/>

```json
"permissions" : {
    "sandbox": ["allow-popups ", "allow-downloads"],
}
```

<InlineAlert slots="text" variant="warning"/>

**IMPORTANT:** When implementing the premium content flows where you present a dialog or option to allow the user to upgrade, you must be sure to also include the following permissions in the `sandbox` attribute of your `manifest.json`. This will allow the Adobe Express pricing page to properly load:

```json
    "entryPoints": [
        {   
            /*... other fields ...*/
            "permissions": {
                "sandbox": ["allow-popups-to-escape-sandbox", "allow-popups", "allow-downloads"]
            }
        }
    ]
```

## Notes

- Files within the add-on bundle can refer to each other via relative paths.
- Changes to your add-on manifest currently require a reload, but you can simply use the **Refresh** button from the **Add-on Development** panel to force the add-on to reload and pick up your manifest changes.

  ![refresh button for manifest changes](../img/refresh-btn.png)
---
keywords:
  - Adobe Express
  - Express Add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
title: Color Picker
description: Adobe Express built-in Color Picker component
contributors:
  - https://github.com/undavide
---

# Built-in UI Components: Color Picker

Adobe Express includes a set of built-in UI Components that provide a consistent experience across different parts of the application.

## Features

The Adobe Express native Color Picker offers several unique features, compared to the Browser's default alternative, for example:

- **Recommended Swatches**: a collection of colors that are curated by Adobe Express to provide a consistent color palette.
- **Themes**: color palettes that are designed to work well together.
- **Library**: collections that you can save and reuse in your designs.
- **Eyedropper**: a tool that allows you to pick a color from anywhere on the screen.
- **Brand colors**: collections of approved swatches and palettes to create consistent branded content

![Color Picker](./images/colorpicker_brand.png)

Using the Adobe ExpressColor Picker in your add-on instead of building your own version provides a few benefits:

- It simplifies the process of selecting a color, bypassing the Browser's color picker.
- It provides a consistent experience to users, as the color picker is integrated with Adobe Express.
- It's in sync with any swatches or Brand colors defined in the application.
- It will evolve with Adobe Express, adding new features over time.

## API

The [`addOnUISdk.app`](../addonsdk/addonsdk-app.md) has two dedicated method:

- [`showColorPicker()`](../addonsdk/addonsdk-app.md#showcolorpicker)
- [`hideColorPicker()`](../addonsdk/addonsdk-app.md#hidecolorpicker)

<InlineAlert variant="info" slots="text" />

Please refer to the [API reference](../addonsdk/addonsdk-app.md) for a complete list of the available options.

### `showColorPicker()`

```js
showColorPicker(
  anchorElement: HTMLElement,
  options?: ColorPickerOptions): Promise<void>;
```

The method accepts a reference to an HTML element as its first argument, which will become the color picker's anchor element. This is important for two reasons:

1. The picker will be positioned relative to this element, based on the placement options available in the [`ColorPickerPlacement`](../addonsdk/addonsdk-constants.md#constants) enumerable;
2. The anchor will receive two custom events:
   - `"colorpicker-color-change"` when the color changes—use it to get the color.
   - `"colorpicker-close"` when the picker is closed—use it to clean up any state.

<InlineAlert variant="warning" slots="text" />

When colors are changed during a drag action (e.g., on the color area or slider), only the final color at the end of the drag will be sent, to avoid performance issues.

The second argument is an object of type [`ColorPickerOptions`](../addonsdk/addonsdk-app.md#colorpickeroptions) that allows you to customize the picker with the following options:

- `title?`: the title of the picker (string, default: `""`).
- `initialColor?`: the color to be selected when the picker is opened (HEX number, default: `0xFFFFFF`).
- `placement?`: the placement of the picker relative to the anchor element (enum, default: `ColorPickerPlacement.left`).
- `eyedropperHidesPicker?`: if `true`, the eyedropper will hide the picker when activated (boolean, default: `false`).
- `disableAlphaChannel?`: if `true`, the alpha channel will be disabled (boolean, default: `false`).

### `hideColorPicker()`

```js
hideColorPicker(): Promise<void>;
```

This method will programmatically close the color picker.

## Examples

<InlineAlert variant="info" slots="text" />

Please also refer to the the Color Picker section of the [Use Color](../../guides/develop/how_to/use_color.md#use-the-color-picker) how-to guide for more examples.

### Basic usage

```js
import addOnUISdk, {
  ColorPickerPlacement,
} from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Basic usage - just show color picker
addOnUISdk.app.showColorPicker(element);

// Example 1: With title, initial color and eyedropper
addOnUISdk.app.showColorPicker(element, {
  title: "Color Picker 1",
  initialColor: 0x00ff00,
  eyedropperHidesPicker: true,
});

// Example 2: With alpha channel disabled
addOnUISdk.app.showColorPicker(element, {
  title: "Color Picker 2",
  initialColor: 0xff0000,
  disableAlphaChannel: true,
});

// Example 3: With initial color only
addOnUISdk.app.showColorPicker(element, {
  title: "Color Picker 3",
  initialColor: 0x0000ff,
});

// Example 4: Basic with title
addOnUISdk.app.showColorPicker(element, {
  title: "Color Picker 4",
});

// Example 5: With title and placement
addOnUISdk.app.showColorPicker(element, {
  title: "Color Picker 5",
  placement: ColorPickerPlacement.bottom,
});
```

### Listening to events

```js
import addOnUISdk, {
  ColorPickerEvents,
} from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  const colorPickerButton = document.getElementById("colorPicker");

  // Add event listeners for color picker events
  colorPickerButton.addEventListener(ColorPickerEvents.colorChange, (event) => {
    console.log("Color picker color change event from add-on:", event.detail);
  });

  colorPickerButton.addEventListener(ColorPickerEvents.close, (event) => {
    console.log("Color picker closed from add-on:", event.detail);
  });

  colorPickerButton.addEventListener("click", () => {
    addOnUISdk.app.showColorPicker(colorPickerButton, {
      title: "JS Color Picker",
      initialColor: 0x00ff00,
      placement: "bottom",
    });
  });
});
```

### Using ReactJS

```jsx
// Example of Color Picker with auto-hide after 10 seconds
<Button
  size="s"
  ref={buttonRef2}
  id="color-picker1"
  style={{ width: "200px" }}
  onClick={() => {
    addOnUISdk.app.showColorPicker(buttonRef2.current, {
      title: "Color Picker 2",
      initialColor: 0xff0000,
      disableAlphaChannel: true,
    });
    setTimeout(() => {
      console.log("Hiding Color Picker 1 after 10 seconds");
      addOnUISdk.app.hideColorPicker();
    }, 10000);
  }}
>
  Color Picker
</Button>
```

## Positioning

The color picker can be positioned relative to the anchor element using the `placement` option in the `ColorPickerOptions` object. The position will be flipped (right to left or bottom to top) when there is not enough space to show the picker in the specified placement.

![Color Picker Placement](./images/colorpicker_position.png)

## Error Conditions

**Invalid anchor element: must be an instance of `HTMLElement`.**

- **Origin:** Parameter `anchorElement`
- **Fix:** the anchorElement should be a valid `HTMLElement`

**Invalid title: must be a string.**

- **Origin:** Property `title` in the `ColorPickerOptions`
- **Fix:** the `title` should be a valid string

**Invalid initial color: must be a HEX number in `0xRRGGBB` format.**

- **Origin:** Property `initialColor` in the `ColorPickerOptions`
- **Fix:** the `initialColor` should be a valid number in 0xRRGGBB format.

**Invalid placement value: must be one of the valid `ColorPickerPlacement` values.**

- **Origin:** Property `placement` in the `ColorPickerOptions`
- **Fix:** the `placement` should be a valid string from the `ColorPickerPlacement` enum.

**Invalid `eyedropperHidesPicker`: must be a boolean value.**

- **Origin:** Property `eyedropperHidesPicker` in the `ColorPickerOptions`
- **Fix:** the `eyedropperHidesPicker` must be a boolean value.

**Invalid `disableAlphaChannel`: must be a boolean value.**

- **Origin:** Property `disableAlphaChannel` in the `ColorPickerOptions`
- **Fix:** the `disableAlphaChannel` must be a boolean value.
---
keywords:
  - Adobe Express
  - Express add-on SDK
  - Express Editor
  - Adobe Express
  - Add-on SDK
  - SDK
  - JavaScript
  - Extend
  - Extensibility
  - API
  - Add-on Manifest
title: Guides
description: A list of the code samples available for build add-ons for Adobe Express.
contributors:
  - https://github.com/hollyschinsky
---

# Code Samples

Find inspiration and great reference examples by checking out our [code samples](https://github.com/AdobeDocs/express-add-on-samples) repo. A description of each sample and which features and technologies they use is available here for reference.

<InlineAlert slots="text" variant="info"/>

In addition to these code samples, you should also be sure to check out the [Templates section](guides/getting_started/dev_tooling.md#templates) in the **Development Tools** page for the options available for creating a starter project based on your favorite development stack.

## Using the samples

- Clone [the repo](https://github.com/AdobeDocs/express-add-on-samples) (or download the zip).
- `cd` into the folder of a sample you want to try.
- Run `npm install` to install the dependencies.
- Run `npm run build` to build the source.
- Run `npm run start` to start to start the server with your bundled sample
- Navigate to Adobe Express and load and use the locally running sample add-on with the add-on panel developer tools just as you would with your own.

**NOTE:** Before you run any samples, you must have previously run the `npx @adobe/create-ccweb-add-on` command to create your own add-on at least once to ensure the package is available and ready to use.

## [get-started](https://github.com/AdobeDocs/express-add-on-samples/tree/main/samples/get-started)

Demonstrates how to get started with add-on development with a simple app that greets a user after a name is entered.

**Technologies Used:** <br/>

- HTML
- JavaScript
- CSS

**Note:** No specific add-on SDK features are used in this sample, it is meant to run a simple JavaScript app that can be loaded and run in the add-ons panel.

## [import-images-from-local](https://github.com/AdobeDocs/express-add-on-samples/tree/main/samples/import-images-from-local)

Demonstrates how to use the add-on SDK's Import and Drag and Drop APIs to add images over click and drag and drop to a document.

**Technologies Used:** <br/>

- JavaScript
- CSS

**Features Leveraged:**<br/>

- [Import Content](./references/addonsdk/app-document.md) to add the image to the document when the gif is clicked.
- [Drag and Drop](./references/addonsdk/addonsdk-app.md#enabledragtodocument) to support dragging and dropping images to the document.

## [import-images-using-oauth](https://github.com/AdobeDocs/express-add-on-samples/tree/main/samples/import-images-using-oauth)

Demonstrates how to use the add-on SDK's OAuth API to allow its users to connect their Dropbox account (in addition to leveraging some others listed below).

**Technologies Used:** <br/>

- React
- React Spectrum
- CSS
- Webpack

**Features Leveraged:**<br/>

- [OAuth API's](./references/addonsdk/app-oauth.md) to authorize the user with the Dropbox service.
- [Import Content](./references/addonsdk/app-document.md) to add images from the add-on to the document.
- [Drag and Drop](./references/addonsdk/addonsdk-app.md#enabledragtodocument) to support dragging and dropping images to the document.
- [Client Storage](./references/addonsdk/instance-clientStorage.md) to store the access_token in the IndexedDB store of the browser and reusing the same for the requests made to the Dropbox APIs.

## [use-client-storage](https://github.com/AdobeDocs/express-add-on-samples/tree/main/samples/use-client-storage)

Demonstrates how to use the Client Storage API to persist user generated data through a todo list.

**Technologies Used:** <br/>

- TypeScript
- CSS
- Webpack

**Features Leveraged:**<br/>

- [Client Storage](./references/addonsdk/instance-clientStorage.md) to persist the todo items.

## [export-sample](https://github.com/AdobeDocs/express-add-on-samples/tree/main/samples/export-sample)

Demonstrates how to use the add-on SDK's to export renditions of content in various formats including jpeg, png, pdf and mp4.

**Technologies Used:** <br/>

- JavaScript
- Spectrum Web Components
- Webpack

**Features Leveraged:**<br/>

- [Export Content](./references/addonsdk/app-document.md) to generate renditions.
- [Import Content](./references/addonsdk/app-document.md) to add the image to the document when the gif is clicked.

## [dialog-add-on](https://github.com/AdobeDocs/express-add-on-samples/tree/main/samples/dialog-add-on)

Demonstrates how to use the Modal Dialog APIs to pop-up variations of modals from your add-ons.

**Technologies Used:** <br/>

- React
- React Spectrum
- Webpack

**Features Leveraged:**<br/>

- [Modal Dialogs](./references/addonsdk/addonsdk-app.md#showmodaldialog) to pop-up a variation of a modal reflecting the selections made from the add-ons panel UI.

## [licensed-addon](https://github.com/AdobeDocs/express-add-on-samples/tree/main/samples/licensed-addon)

Demonstrates how to utilize the hash of the user ID to integrate an add-on with licensing and payment services and monetize effectively.

**Technologies Used:** <br/>

- React
- React Spectrum
- Webpack

**Features Leveraged:**<br/>

- [Current User API](./references/addonsdk/app-currentUser.md) to validate the current userid's.
- [Modal Dialogs](./references/addonsdk/addonsdk-app.md#showmodaldialog) to pop-up a modal.

## [audio-recording-addon](https://github.com/AdobeDocs/express-add-on-samples/tree/main/samples/audio-recording-add-on)

Demonstrates how to record audio using the browser's media recorder API, converting the raw Blob into a `WAV` Blob and using the document's `addAudio()` API.

**Technologies Used:** <br/>

- JavaScript

**Features Leveraged:**<br/>

- Record audio using the Browser's API, transforming a raw Blob into a WAV Blob using an HPC codec.
- [Add audio](./references/addonsdk/app-document.md#addaudio) to the current document's page.

<!-- # Contributed Add-on Samples
The following samples were contributed from the team. -->

## [pix](https://github.com/AdobeDocs/express-add-on-samples/tree/main/contributed/pix)

A react-based add-on that illustrates a very simple 16x16 pixel editor add-on. Users can drag the resulting pixel art on to the canvas, but they can also import the current page as pixel art (downsampled to 16x16).

**Technologies Used:** <br/>

- HTML Canvas
- React
- Spectrum Web Components
- Webpack

**Features Leveraged:**<br/>

- [Drag and Drop](./references/addonsdk/addonsdk-app.md#enabledragtodocument) to add the dragged image to the document.
- [Export Content](./references/addonsdk/app-document.md) to generate renditions.
- [Client Storage](./references/addonsdk/instance-clientStorage.md) to store the pixel art creations.

## [swc](https://github.com/AdobeDocs/express-add-on-samples/tree/main/contributed/swc)

Simple sample which illustrates how to use **Spectrum Web Components** without React or any other framework.

**Technologies Used:** <br/>

- HTML
- CSS
- JavaScript
- Spectrum Web Components
- Webpack

**Features Leveraged:**<br/>

- [Application UI Theme](./references/addonsdk/app-ui.md) to set the theme (only once the SDK is loaded to prevent any flash of unstyled content) and to listen and respond to theme changes.

## [swc-react-theme-sampler](https://github.com/AdobeDocs/express-add-on-samples/tree/main/contributed/swc-react-theme-sampler)

Demonstrates the use of the [SWC-React](https://opensource.adobe.com/spectrum-web-components/using-swc-react/) library, a set of React wrapper components for Spectrum Web Components (SWC), as well as illustrates some of the different [Spectrum theme](https://opensource.adobe.com/spectrum-web-components/tools/theme/) component properties provided with Spectrum (ie: main *Express* theme, *scale* and *color*) and how they affect the UI.

**Technologies Used:** <br/>

- React
- SWC-React
- Webpack

**Features Leveraged:**<br/>

- [Application UI Theme](./references/addonsdk/app-ui.md) to set the theme and to listen and respond to theme changes.

## [vue-starter](https://github.com/AdobeDocs/express-add-on-samples/tree/main/contributed/vue-starter)

Simple sample which illustrates how to use **Spectrum Web Components** without React or any other framework.

**Technologies Used:** <br/>

- Vue.js
- HTML
- JavaScript
- Webpack
- CSS

**Features Leveraged:**<br/>

- [Add-on SDK Ready](./references/addonsdk/addonsdk.md) method is checked to ensure the SDK is loaded before enabling the button in the UI (similar to the templates generated with our CLI, but based on Vue.js).

<!-- # Marketplace Add-on Samples
The following samples were built to show how to use specific some popular 3rd party services. -->

<!-- ## [Dropbox](https://github.com/AdobeDocs/express-add-on-samples/tree/main/marketplace/dropbox)
Allows users to connect to their Dropbox account. Once connected, they can fetch their images and videos from their account and add them to their Express pages.

**Technologies Used:** <br/>

- React
- React Spectrum
- Webpack

**Features Leveraged:**<br/>

- [OAuth API's](./references/addonsdk/app-oauth.md) to authorize the user with the Dropbox service.
- [Drag and Drop](./references/addonsdk/addonsdk-app.md#enabledragtodocument) to support dragging and dropping images to the document.
- [Import Content](./references/addonsdk/app-document.md) to add the image to the document when the gif is clicked. -->

## [Giphy](https://github.com/AdobeDocs/express-add-on-samples/tree/main/marketplace/giphy)

Allows users to search for popular gifs and add them to the document.

**Technologies Used:** <br/>

- JavaScript
- Spectrum Web Components

**Features Leveraged:**<br/>

- [Drag and Drop](./references/addonsdk/addonsdk-app.md#enabledragtodocument) to support dragging and dropping images to the document.
- [Import Content](./references/addonsdk/app-document.md) to add the image to the document when the gif is clicked.

## [QR Code](https://github.com/AdobeDocs/express-add-on-samples/tree/main/marketplace/qrcode)

Allows users to create a QR code based on a URL and add it to their document.

**Technologies Used:** <br/>

- JavaScript
- Spectrum Web Components

**Features Leveraged:**<br/>

- [Import Content](./references/addonsdk/app-document.md) to add the QR Code image to the document when it's clicked.
- [Drag and Drop](./references/addonsdk/addonsdk-app.md#enabledragtodocument) to support dragging and dropping QR Codes to the document.

## [gradients](https://github.com/AdobeDocs/express-add-on-samples/tree/main/marketplace/gradients)

Allows users to create two-color gradients of various shapes and direction, and add them to their Adobe Express project.

**Technologies Used:** <br/>

- Lit Web Components
- Spectrum Web Components
- 2D Canvas
- TypeScript

**Features Leveraged:**<br/>

- [Create Bitmap Image](./references/document-sandbox/document-apis/classes/Editor.md#createimagecontainer) in the document from bitmap data generated in the add-on iframe UI.

## Document Sandbox Code Samples

The following [code samples](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples) have been provided to help you get started using the [Document Sandbox and Adobe Express Document APIs](./references/document-sandbox/index.md).

## [express-grids-addon](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/express-grids-addon)

The sample add-on that the [Grid System tutorial](./guides/tutorials/grids-addon.md) is based upon. Demonstrates how to use the [Document APIs](./references/document-sandbox/index.md) to create and manipulate shapes, context permanence, color pickers, and Spectrum Web Components usage.

## [express-stats-addon](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/express-stats-addon)

The sample add-on that the [Document Statistics tutorial](./guides/tutorials/stats-addon.md) is based upon. It demonstrates how to use the [Communication APIs](./references/document-sandbox/communication/index.md) to invoke Document Sandbox method from the iframe UI and vice-versa, touching on asynchronous communication and context permanence. The add-on can build a list of statistics for the document, e.g., the number of class instances (shapes, text, images, and so on).

## [express-dimensions-addon](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/express-dimensions-addon)

The sample add-on that the [Document APIs Concepts](./references/document-sandbox/document-apis/concepts/index.md) article is based upon. It's used to discuss the Adobe Express Document Object Model, its Classes, Interface, and Constants. The add-on draws Dimensions (arrows measuring the width and height) around the selected shape.

## [communication-iframe-documentSandbox](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/communication-iframe-documentSandbox)

Demonstrates using the Communication APIs to expose and proxy APIs bidirectionally between the iframe and document sandbox code environments via [`runtime.apiProxy()`](/references/addonsdk/instance-runtime.md#apiproxy) and [`runtime.exposeApi()`](/references/addonsdk/instance-runtime.md#exposeapi).

## [editor-apis](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/editor-apis)

Demonstrates how to use the [Document APIs](./references/document-sandbox/document-apis/) to create various shapes and text, and add them to the document.

## [image-and-page](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/image-and-page)

A more comprehensive example of using the [Document APIs](./references/document-sandbox/document-apis/) to add a page, images, and shapes, and clear the artboard.

## [express-addon-document-api-template](https://github.com/AdobeDocs/express-add-on-samples/tree/main/document-sandbox-samples/express-addon-document-api-template)

A barebone JavaScript template that implements the Document APIs.