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

# Page background

Set and modify page background colors and images.

## Running this example

To run this example locally:

1. If you haven't already, create a new app in the [Developer Portal](https://www.canva.com/developers/apps). For more information, refer to our [Quickstart guide](https://www.canva.dev/docs/apps/quickstart/).

2. In your app's configuration on the [Developer Portal](https://www.canva.com/developers/apps), ensure the "Development URL" is set to `http://localhost:8080`.

3. Clone the starter kit:

   ```shell
   git clone https://github.com/canva-sdks/canva-apps-sdk-starter-kit.git
   cd canva-apps-sdk-starter-kit
   ```

4. Install dependencies:

   ```shell
   npm install
   ```

5. Run the example:
   ```shell
   npm run start:example page_background
   ```

6. Click the **Preview URL** link shown in the terminal to open the example in the Canva editor.

## Example app source code

<Tabs>
  <Tab name="app.tsx">
    ```typescript
    // For usage information, see the README.md file.
    import { upload } from "@canva/asset";
    import { Alert, Button, Rows, Text } from "@canva/app-ui-kit";
    import { setCurrentPageBackground } from "@canva/design";
    import * as styles from "styles/components.css";
    import { useState } from "react";
    import { useFeatureSupport } from "@canva/app-hooks";

    export const App = () => {
      const [loading, setLoading] = useState(false);

      // Check if the current design type supports page background changes
      // (Some design types like docs don't support background modification)
      const isSupported = useFeatureSupport();
      const isRequiredFeatureSupported = isSupported(setCurrentPageBackground);

      const setBackgroundToSolidColor = async () => {
        setLoading(true);
        // Set the page background to a solid color using hex color value
        await setCurrentPageBackground({
          color: "#ff0099",
        });
        setLoading(false);
      };

      const setBackgroundImage = async () => {
        setLoading(true);

        // Upload an external image asset to Canva for use as background
        // The upload function returns a reference that can be used with Canva APIs
        const { ref } = await upload({
          type: "image",
          mimeType: "image/jpeg",
          url: "https://www.canva.dev/example-assets/image-import/image.jpg",
          thumbnailUrl:
            "https://www.canva.dev/example-assets/image-import/thumbnail.jpg",
          width: 540,
          height: 720,
          aiDisclosure: "none",
        });

        // Apply the uploaded image as the page background
        await setCurrentPageBackground({
          asset: { type: "image", ref },
        });
        setLoading(false);
      };

      const setBackgroundVideo = async () => {
        setLoading(true);

        // Upload an external video asset to Canva for use as background
        // Videos require both image and video thumbnails for preview
        const { ref } = await upload({
          type: "video",
          mimeType: "video/mp4",
          url: "https://www.canva.dev/example-assets/video-import/video.mp4",
          thumbnailImageUrl:
            "https://www.canva.dev/example-assets/video-import/thumbnail-image.jpg",
          thumbnailVideoUrl:
            "https://www.canva.dev/example-assets/video-import/thumbnail-video.mp4",
          width: 405,
          height: 720,
          aiDisclosure: "none",
        });

        // Apply the uploaded video as the page background
        await setCurrentPageBackground({
          asset: { type: "video", ref },
        });
        setLoading(false);
      };

      return (
        <div className={styles.scrollContainer}>
          <Rows spacing="2u">
            <Text>
              This example demonstrates how apps can set the background of the
              current page.
            </Text>
            <Button
              stretch
              loading={loading}
              // Set page background is not supported in certain design type such as docs.
              disabled={loading || !isRequiredFeatureSupported}
              variant="secondary"
              onClick={setBackgroundToSolidColor}
            >
              Set background to a solid color
            </Button>
            <Button
              stretch
              variant="secondary"
              loading={loading}
              // Set page background is not supported in certain design type such as docs.
              disabled={loading || !isRequiredFeatureSupported}
              onClick={setBackgroundImage}
            >
              Set background to an image
            </Button>
            <Button
              stretch
              variant="secondary"
              loading={loading}
              // Set page background is not supported in certain design type such as docs.
              disabled={loading || !isRequiredFeatureSupported}
              onClick={setBackgroundVideo}
            >
              Set background to a video
            </Button>
            {!isRequiredFeatureSupported && <UnsupportedAlert />}
          </Rows>
        </div>
      );
    };

    const UnsupportedAlert = () => (
      <Alert tone="warn">
        Sorry, the required features are not supported in the current design.
      </Alert>
    );
    ```
  </Tab>

  <Tab name="index.tsx">
    ```typescript
    // For usage information, see the README.md file.
    import { AppUiProvider } from "@canva/app-ui-kit";
    import { createRoot } from "react-dom/client";
    import { App } from "./app";
    import "@canva/app-ui-kit/styles.css";
    import type { DesignEditorIntent } from "@canva/intents/design";
    import { prepareDesignEditor } from "@canva/intents/design";

    async function render() {
      const root = createRoot(document.getElementById("root") as Element);

      root.render(
        <AppUiProvider>
          <App />
        </AppUiProvider>,
      );
    }

    const designEditor: DesignEditorIntent = { render };
    prepareDesignEditor(designEditor);

    // Hot Module Replacement for development (automatically reloads the app when changes are made)
    if (module.hot) {
      module.hot.accept("./app", render);
    }
    ```
  </Tab>

  <Tab name="README.md">
    ```markdown
    # Page background

    Demonstrates how to set page backgrounds using solid colors, images, and videos. Shows background customization, asset upload for backgrounds, and background type handling.

    For API reference docs and instructions on running this example, see: https://www.canva.dev/docs/apps/examples/page-background/.

    Related examples: See design_interaction/page_addition for creating new pages, or asset_upload for general asset handling patterns.

    NOTE: This example differs from what is expected for public apps to pass a Canva review:

    - Static assets are used for demonstration purposes only. Production apps should host assets on a CDN/hosting service and use the `upload` function from the `@canva/asset` package
    - Asset validation is simplified for demonstration. Production apps should validate background assets and handle unsupported formats gracefully
    - Error handling is simplified for demonstration. Production apps must implement comprehensive error handling with clear user feedback and graceful failure modes
    - Internationalization is not implemented. Production apps must support multiple languages using the `@canva/app-i18n-kit` package to pass Canva review requirements
    - The code structure is simplified: Production apps using [intents](https://www.canva.dev/docs/apps/intents/) are recommended to call the prepareDesignEditor function from src/intents/design_editor/index.tsx
    ```
  </Tab>
</Tabs>

## API reference

* [App UI Kit](https://www.canva.dev/docs/apps/app-ui-kit/)
* [`prepareDesignEditor`](https://www.canva.dev/docs/apps/api/latest/intents-design-prepare-design-editor/)
* [`setCurrentPageBackground`](https://www.canva.dev/docs/apps/api/latest/design-set-current-page-background/)
* [`upload`](https://www.canva.dev/docs/apps/api/latest/asset-upload/)

## Need help?

* Join our [Community Forum](https://community.canva.dev/)
* Report issues with this example on [GitHub](https://github.com/canva-sdks/canva-apps-sdk-starter-kit/issues)