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

# App UI Kit v4 to v5 Migration Guide

Upgrade your app from App UI Kit v4 to v5.

Version 5 of the App UI Kit includes new design tokens that replace the v4 tokens with a new naming system and improved semantic structure.

This page provides the complete mapping from v4 to v5 design tokens to help you upgrade your app.

For more information about design tokens and when to use them, see the [design tokens overview](https://www.canva.dev/docs/apps/app-ui-kit/design-tokens/).

There are also some breaking changes in the component library. For the full list of changes, see the [changelog](https://www.canva.dev/docs/apps/app-ui-kit/changelog/#501-2025-09-30) .

## What's changing?

The App UI Kit v5 introduces a new design token system with:

* **Improved semantic naming**: Tokens now have clearer, more descriptive names.
* **Better organization**: Tokens are grouped by purpose (action, content, feedback, and so on).
* **Enhanced consistency**: More consistent naming patterns across all token types.

There are also some breaking changes to the properties of the `Link`, `Pill`, `InputPill`, `Columns`, and `ColorSelector` components.

Finally, we have upgraded from React 18 to 19 so you may have other dependencies that need to change, or breaking changes in React to accommodate. For more information about upgrading to React 19, see the [react.dev upgrade guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide).

## How to automatically migrate

Run the `app-ui-kit-v5` Canva CLI apps migrate command in your app's project directory to use the Canva CLI to automatically migrate your app to use App UI Kit v5:

```bash
npx @canva/cli@latest apps migrate app-ui-kit-v5
```

It automatically runs through the code changes required to install the updated dependencies, migrates design tokens, and changes component properties.

## How to manually migrate

1. **Update your dependencies**: Upgrade to the latest version of `@canva/app-ui-kit`.
2. **Find and replace tokens**: Use the tables below to map your v4 tokens to v5 tokens.
3. **Update components**: There are some small breaking changes to component properties in v5.
4. **Test your app**: Verify that your app still looks and works correctly.

### Migration example

Here's an example of migrating a CSS class from v4 to v5 tokens:

**Before (v4 tokens):**

```css
.my-component {
  background-color: var(--ui-kit-color-primary);
  color: var(--ui-kit-color-typography-primary);
  padding: var(--ui-kit-space-2);
}
```

**After (v5 tokens):**

```css
.my-component {
  background-color: var(--ui-kit-color-action-primary-bg);
  color: var(--ui-kit-color-content-fg);
  padding: var(--ui-kit-space-200);
}
```

### Do I need to migrate the design tokens?

* **If you only use App UI Kit components**: You don't need to do anything. The components will automatically use the new v5 tokens.

* **If you use design tokens directly in your CSS or TypeScript**: You'll need to update your code to use the new v5 token names.

## Migration mappings

The tables below show the complete mapping from v4 to v5 design tokens.

### Color tokens

### Shadow and surface tokens

### Spacing tokens

### Component changes

In addition to design token changes, App UI Kit v5 includes several component updates:

#### React version requirement

* **Breaking**: React 19 is now required and React 18 support was removed.

  **Migration**: Update your project to use React v19.

#### Link component

* **Breaking**: Removed deprecated `title` prop.

  **Migration**: Use `tooltipLabel` instead of `title`.

```tsx
// Before (v4)
<Link title="Click here" href="/example">Link text</Link>

// After (v5)
<Link tooltipLabel="Click here" href="/example">Link text</Link>
```

#### ColorSelector component

* **Breaking**: The `source` parameter in `onChange` callback is now optional.

  **Migration**: Check for `undefined` values in your callback handler.

```tsx
// Before (v4)
<ColorSelector onChange={(color, source) => {
  // source was always defined
  console.log(source);
}} />

// After (v5)
<ColorSelector onChange={(color, source) => {
  // source might be undefined
  if (source) {
    console.log(source);
  }
}} />
```

#### Column component

* **Breaking**: Default `alignY` property changed from implicit to `stretch`.

  **Migration**: To use the old behavior, explicitly set `alignY="start"`.

```tsx
// Before (v4) - implicit start alignment
<Column>Content</Column>

// After (v5) - explicit start alignment needed
<Column alignY="start">Content</Column>
```

#### Pill and InputPill components

* **Breaking**: Replaced `truncateText` prop with `maxWidth` prop.
* **Breaking**: Changed `size` values: `"small"` is now `"xsmall"`.
* **Breaking**: Pill has a rounder appearance for consistency with other Canva elements.
* **Breaking**: Removed `tone` property.

```tsx
// Before (v4)
<Pill size="small" truncateText>Text</Pill>
<InputPill truncateText={false}>Text</InputPill>

// After (v5)
<Pill size="xsmall" maxWidth='25u'>Text</Pill>
<InputPill maxWidth='100%'>Text</InputPill>
```

#### Global styling

* **Breaking**: Removed the default `colorSurface` background color from the `html` tag.

  A migration isn't be required, the Canva environment has changed to accommodate this.

#### New components

* **Added**: `LinkButton` component for in-app actions that don't open URLs.

  Use `LinkButton` instead of `Button` when you need link-style interactions without navigation