> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pixy.art/llms.txt
> Use this file to discover all available pages before exploring further.

# How to use

> Choose the right Pixy embed launch mode and handle saved designs correctly.

## Add the SDK

Load the Pixy embed SDK on the page where you want to launch the editor.

```html theme={null}
<script src="https://app.pixy.art/embed/sdk"></script>
```

Use the SDK when your app needs an `onExport` callback. Use the iframe fallback only when you do not need a callback into your app.

## Choose a launch scenario

<AccordionGroup>
  <Accordion title="Existing design" icon="file-pen-line">
    Use this when the user should continue editing the same saved design.

    Behavior:

    * opens the design identified by `designId`
    * does not create a copy before loading
    * save/export returns the same design id through `onExport`
    * use the returned `designId` to reopen the same design later

    ```html theme={null}
    <script src="https://app.pixy.art/embed/sdk"></script>
    <div id="pixy" style="width: 100%; height: 900px;"></div>
    <script>
      window.Pixy.mount('#pixy', {
        embedKey: 'YOUR_EMBED_KEY',
        designId: 'YOUR_DESIGN_ID',
        onExport: (result) => {
          console.log(result.designId)
          console.log(result.files)
        },
      })
    </script>
    ```

    Use this for saved user projects, drafts, or any workflow where reopening the design should continue from the previous state.
  </Accordion>

  <Accordion title="Existing design as a copy" icon="copy">
    Use this when an existing design should behave like a template.
    This is required when the source `designId` is a public template returned by the Templates API.

    Behavior:

    * looks up the source design by `designId`
    * creates a new design copy when the editor loads, even before the user exports
    * opens the new copied design, not the original source design
    * keeps the original source design unchanged
    * save/export returns the new copied design id through `onExport`
    * every launch with `openAsCopy: true` creates another new copy

    ```html theme={null}
    <script src="https://app.pixy.art/embed/sdk"></script>
    <div id="pixy" style="width: 100%; height: 900px;"></div>
    <script>
      window.Pixy.mount('#pixy', {
        embedKey: 'YOUR_EMBED_KEY',
        designId: 'YOUR_TEMPLATE_DESIGN_ID',
        openAsCopy: true,
        onExport: (result) => {
          console.log(result.designId)
          console.log(result.files)
        },
      })
    </script>
    ```

    Store the returned `result.designId` if the user should continue editing that copy later. To reopen that saved copy, launch with the returned `designId` and leave `openAsCopy` off.

    Your app receives the copied design id only after `onExport` runs. If the user opens the editor and closes it without saving, the copy may already exist in Pixy, but your app will not receive that new id.
  </Accordion>

  <Accordion title="Blank canvas" icon="square">
    Use this when the editor should start with an empty design.

    Behavior:

    * creates a new design with the provided `width` and `height`
    * does not require a template or existing design
    * creates the blank design when the editor loads, even before the user exports
    * save/export returns the new design id through `onExport`
    * use the returned `designId` to reopen the design later

    ```html theme={null}
    <script src="https://app.pixy.art/embed/sdk"></script>
    <div id="pixy" style="width: 100%; height: 900px;"></div>
    <script>
      window.Pixy.mount('#pixy', {
        embedKey: 'YOUR_EMBED_KEY',
        width: 1080,
        height: 1350,
        onExport: (result) => {
          console.log(result.designId)
          console.log(result.files)
        },
      })
    </script>
    ```

    You must provide both `width` and `height` for a blank canvas.

    Your app receives the new blank design id only after `onExport` runs. If the user opens the editor and closes it without saving, the design may already exist in Pixy, but your app will not receive that new id.
  </Accordion>
</AccordionGroup>

For optional per-launch fields like `userId`, `saveButtonLabel`, and `imageUrls`, see [Optional parameters](/embed/optional-parameters).

Do not mix `designId` with `width` and `height`. If you pass a `designId`, the editor uses that design path.
Public template IDs returned by the Templates API are copy-only in Embed: pass the template `id` as `designId` and set `openAsCopy: true`.

## Appearance

The launch scenario controls which design opens. Inline and modal only control how the editor appears.

<AccordionGroup>
  <Accordion title="Inline" icon="panel-left">
    Inline mounts the editor inside your page. In inline mode, the editor stays open after save.

    ```js theme={null}
    window.Pixy.mount('#pixy', {
      embedKey: 'YOUR_EMBED_KEY',
      designId: 'YOUR_DESIGN_ID',
      saveButtonLabel: 'Schedule',
      onExport: (result) => {
        console.log(result)
      },
    })
    ```
  </Accordion>

  <Accordion title="Modal" icon="external-link">
    Modal opens the editor in an overlay. In modal mode, a successful save calls `onExport` and then closes the modal automatically.

    ```html theme={null}
    <script src="https://app.pixy.art/embed/sdk"></script>
    <button id="open-pixy">Open editor</button>
    <script>
      const pixy = window.Pixy.create({
        embedKey: 'YOUR_EMBED_KEY',
        designId: 'YOUR_DESIGN_ID',
        saveButtonLabel: 'Schedule',
        onExport: (result) => {
          console.log(result)
        },
      })

      document
        .getElementById('open-pixy')
        .addEventListener('click', () => pixy.open())
    </script>
    ```
  </Accordion>
</AccordionGroup>

## Export Callback

When `onExport` is provided, the embedded editor shows an `Export` button that sends the export result back to your app.

`onExport` receives the render id, the saved design id, duration, and uploaded export files.

Use `saveButtonLabel` when you need the save button to match your workflow. For details, see [Optional parameters](/embed/optional-parameters).

```js theme={null}
{
  id: 'YOUR_RENDER_ID',
  designId: 'SAVED_DESIGN_ID',
  duration: 1240,
  files: [
    {
      mimetype: 'image/png',
      url: 'https://cdn.pixy.art/...',
      width: 1080,
      height: 1080,
      size: 245182,
    },
  ],
}
```

Important details:

* `result.designId` is the design that was actually saved
* for a normal existing design, this is the original `designId`
* for `openAsCopy: true`, this is the new copied design id
* for a blank canvas, this is the new blank design id
* each successful embed save consumes credits based on the number of exported files

## Iframe Fallback

Use a plain iframe only when you do not need `onExport`.

<CodeGroup>
  ```html Existing design theme={null}
  <iframe
    src="https://app.pixy.art/embed/editor?embedKey=YOUR_EMBED_KEY&designId=YOUR_DESIGN_ID"
    width="100%"
    height="720"
    style="border:0;"
  ></iframe>
  ```

  ```html Existing design as copy theme={null}
  <iframe
    src="https://app.pixy.art/embed/editor?embedKey=YOUR_EMBED_KEY&designId=YOUR_TEMPLATE_DESIGN_ID&openAsCopy=true"
    width="100%"
    height="720"
    style="border:0;"
  ></iframe>
  ```

  ```html Blank canvas theme={null}
  <iframe
    src="https://app.pixy.art/embed/editor?embedKey=YOUR_EMBED_KEY&width=1080&height=1080"
    width="100%"
    height="720"
    style="border:0;"
  ></iframe>
  ```

  ```html Blank canvas with image uploads theme={null}
  <iframe
    src="https://app.pixy.art/embed/editor?embedKey=YOUR_EMBED_KEY&imageUrls=https%3A%2F%2Fexample.com%2Fproduct-front.png&imageUrls=https%3A%2F%2Fexample.com%2Fproduct-back.png"
    width="100%"
    height="720"
    style="border:0;"
  ></iframe>
  ```
</CodeGroup>