If you haven't already, create a new app in the Developer Portal⁠(opens in a new tab or window). For more information, refer to our Quickstart guide.
In your app's configuration on the Developer Portal⁠(opens in a new tab or window), ensure the "Development URL" is set to http://localhost:8080.

Clone the starter kit:

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

SHELL

Install dependencies:
```
npm install
```
SHELL
Run the example:
```
npm run start page_background
```
SHELL
Click the Preview URL link shown in the terminal to open the example in the Canva editor.

Example app source code

// 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 "utils/use_feature_support";

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

  const setBackgroundToSolidColor = async () => {
    setLoading(true);
    await setCurrentPageBackground({
      color: "#ff0099",
    });
    setLoading(false);
  };

  const setBackgroundImage = async () => {
    setLoading(true);
    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",
    });
    await setCurrentPageBackground({
      asset: { type: "image", ref },
    });
    setLoading(false);
  };

  const setBackgroundVideo = async () => {
    setLoading(true);
    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",
    });
    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>
);

TYPESCRIPT

import { AppUiProvider } from "@canva/app-ui-kit";
import { createRoot } from "react-dom/client";
import { App } from "./app";
import "@canva/app-ui-kit/styles.css";

const root = createRoot(document.getElementById("root") as Element);
function render() {
  root.render(
    <AppUiProvider>
      <App />
    </AppUiProvider>,
  );
}

render();

if (module.hot) {
  module.hot.accept("./app", render);
}

TYPESCRIPT

# 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

MARKDOWN

API Reference

Need Help?

Join our Community Forum⁠(opens in a new tab or window)
Report issues with this example on GitHub⁠(opens in a new tab or window)