> ## 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.

# Design metadata

Retrieve and access design metadata and properties.

## 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 design_metadata
   ```

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 {
      Button,
      FormField,
      MultilineInput,
      Rows,
      Text,
    } from "@canva/app-ui-kit";

    import type { DesignMetadata, PageMetadata } from "@canva/design";
    import { getCurrentPageMetadata, getDesignMetadata } from "@canva/design";

    import * as styles from "styles/components.css";
    import React, { useState } from "react";

    export const App = () => {
      // State to store the design metadata retrieved from the Canva Design API
      const [designMetadata, setDesignMetadata] = useState<
        DesignMetadata | undefined
      >();
      // State to store metadata for the page the user is currently viewing
      const [currentPageMetadata, setCurrentPageMetadata] = useState<
        PageMetadata | undefined
      >();

      // Function to fetch design metadata using the Canva Design API
      const getDesignInfo = React.useCallback(async () => {
        // The getDesignMetadata function returns metadata about the current design
        // including title, dimensions, and pageMetadata. Absolute pages include a
        // stable id (PageId) that uniquely identifies the page within the design.
        const response = await getDesignMetadata();
        setDesignMetadata(response);
      }, []);

      // Function to fetch metadata for the current page
      const getCurrentPageInfo = React.useCallback(async () => {
        // getCurrentPageMetadata returns metadata for the page the user is on,
        // including a stable id when the page type is "absolute".
        const response = await getCurrentPageMetadata();
        setCurrentPageMetadata(response);
      }, []);

      return (
        <div className={styles.scrollContainer}>
          <Rows spacing="3u">
            <Text>
              This example demonstrates how apps can retrieve information about the
              design and its pages, including stable page IDs.
            </Text>
            <Button variant="primary" onClick={getDesignInfo} stretch>
              Get design metadata
            </Button>

            {/* Display the design metadata as formatted JSON */}
            <FormField
              label="Design metadata"
              value={JSON.stringify(designMetadata, null, 2)}
              control={(props) => (
                <MultilineInput {...props} maxRows={12} autoGrow readOnly />
              )}
            />

            <Button variant="primary" onClick={getCurrentPageInfo} stretch>
              Get current page metadata
            </Button>

            {/* Display the current page metadata as formatted JSON */}
            <FormField
              label="Current page metadata"
              value={JSON.stringify(currentPageMetadata, null, 2)}
              control={(props) => (
                <MultilineInput {...props} maxRows={8} autoGrow readOnly />
              )}
            />
          </Rows>
        </div>
      );
    };
    ```
  </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
    # Design metadata

    Demonstrates how to retrieve design information including title, dimensions, and page metadata with stable page IDs. Also shows how to get metadata for the page the user is currently viewing with `getCurrentPageMetadata`.

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

    Related examples: See design_interaction/design_token for accessing designs via external APIs, or design_interaction/export for design export functionality.

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

    - Metadata handling is simplified for demonstration purposes only. Production apps should handle metadata gracefully and use metadata for context-aware functionality
    - 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/)
* [`getCurrentPageMetadata`](https://www.canva.dev/docs/apps/api/latest/design-get-current-page-metadata/)
* [`getDesignMetadata`](https://www.canva.dev/docs/apps/api/latest/design-get-design-metadata/)
* [`prepareDesignEditor`](https://www.canva.dev/docs/apps/api/latest/intents-design-prepare-design-editor/)

## 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)