> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.webflow.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.webflow.com/_mcp/server.

# App Modes

## Modes in the Webflow Designer

The Webflow Designer is a powerful collaborative tool for teams to design and build websites quickly and at scale. To support collaboration, the Designer offers various modes to support different aspects of the design process:

* **[Designing and Building](https://help.webflow.com/hc/en-us/articles/33961210206483-Page-building):** Designers can create and refine the website’s layout and appearance in the Webflow Designer, while marketers and content writers manage and update content in build mode.
* **[Page Branching](https://help.webflow.com/hc/en-us/articles/46651751861139-Page-branching):** Multiple designers can work on different pages of the same site at the same time, allowing for parallel development and reducing bottlenecks.
* **[Localization](https://help.webflow.com/hc/en-us/articles/33961240752147-Localization-overview)**: Global teams can create customized experiences for different languages or regions, enabling global reach and tailored content for diverse audiences.

Through these features and modes, the Webflow Designer determines the specific actions a user can take to ensure teams make the right updates at the right time.

## Modes in Webflow Apps

Designer Extensions extend the user’s capabilities while respecting the mode the Designer is in. Each method in the Designer API offers distinct functionality, aligning with the actions feasible  in each mode. By understanding the various modes in the Designer, and how Designer APIs interact  with them, you can ensure your App functions correctly across different contexts within the Webflow Designer, thus providing a seamless user experience.

## Understanding modes and API methods

Each API method’s documentation includes an “App Modes” section that outlines where and how the API can be used, as well as any limitations.

Here’s an example from the “[Remove Element](https://developers.webflow.com/designer/reference/remove-element)” method:

| **Ability**                   | **Locale**                                                                       | **Branch**                                                                     | **Workflow**                                                                                        | **Sitemode**                                                  |
| ----------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| *Name of the current ability* | Site uses Localization, and the user is working in a primary or secondary locale | Site uses Page Branching, and the users working in a primary or branched paged | Determines whether the user is actively working on the canvas, or viewing the site in preview mode. | Determines whether the user is in design mode, or build mode. |
| **canDesign**                 | `primary`                                                                        | `main`                                                                         | `canvas`                                                                                            | `design`                                                      |

In this example, the “Remove Element” method can only be successfully called if the user is in design sitemode, working on the canvas in a primary locale on the main branch. If the user is in the wrong Designer mode, the API throws a `ModeForbidden` error. If the user lacks the required role, locale, or branch, the API throws a `Forbidden` error.

See below for a complete table of abilities, which defines where and how an API method can be used.

| **Name**                  | **Locale** | **Branch** | **Workflow** | **Sitemode** |
| ------------------------- | ---------- | ---------- | ------------ | ------------ |
| **canManageAssets**       | Any        | Any        | Any          | Any          |
| **canAccessAssets**       | Any        | Any        | Any          | Any          |
| **canAccessCanvas**       | Any        | Any        | Any          | Any          |
| **canDesign**             | primary    | main       | canvas       | design       |
| **canEdit**               | Any        | Any        | canvas       | Any          |
| **canCreateComponents**   | primary    | Any        | canvas       | Any          |
| **canModifyComponents**   | Any        | Any        | canvas       | design       |
| **canCreateStyles**       | primary    | Any        | canvas       | design       |
| **canModifyStyles**       | Any        | Any        | canvas       | design       |
| **canCreatePage**         | Any        | Any        | Any          | design       |
| **canReadPageSettings**   | Any        | Any        | Any          | Any          |
| **canManagePageSettings** | Any        | Any        | Any          | Any          |
| **canReadVariables**      | Any        | Any        | Any          | Any          |
| **canModifyVariables**    | Any        | main       | canvas       | design       |
| **canModifyImageElement** | Any        | main       | canvas       | Any          |

<br />

## Checking for App modes with `webflow.canForAppMode`

To ensure your app functions correctly in the different modes of the Webflow Designer, you can leverage the [`webflow.canForAppMode`](https://developers.webflow.com/designer/reference/get-users-designer-capabilities)  method. This method allows you to check whether a specific action is allowed in the user's current mode before executing it, helping to prevent errors and improve the user experience.

#### Example Usage

The `webflow.canForAppMode` method returns a Boolean indicating whether the specified action is permitted based on the current mode of the Designer. Here’s a basic example:

```javascript
const capabilities = await webflow.canForAppMode([webflow.appModes.canDesign, webflow.appModes.canEdit
]);

if (capabilities.canDesign) {
  // Proceed with the action
  const el = await webflow.getSelectedElement();
  await el.append(webflow.elementPresets.DOM);
} else {
  // Provide feedback to the user
  await webflow.notify({
    type: 'Error',
    message: 'This action cannot be performed right now. Ensure you are working in the Primary Locale, on the Main Branch, and in design mode.',
  });
}
```

### When to Use `webflow.canForAppMode`

Use `webflow.canForAppMode` before any critical action that depends on the mode the user is in, such as:

* Adding or modifying elements in the Designer.
* Creating or editing styles that are only permitted in specific locales or branches.
* Managing components that might be restricted based on the current workflow.

[See the documentation for `webflow.canForAppMode` for more details.](https://developers.webflow.com/designer/reference/get-users-designer-capabilities)

## Detecting the current mode

In addition to the `webflow.canForAppMode()` method, the Designer API provides two methods for on-demand mode detection:

* [`webflow.getCurrentMode()`](/designer/reference/get-current-mode): Returns the name of the current Designer mode, or `null` when the Designer's internal state does not map to a public mode.
* [`webflow.isMode()`](/designer/reference/is-mode): Returns a boolean that shows whether the Designer is in a specific mode.

Use these methods to read the active mode on demand, such as when your extension launches or before running an action.
The Designer exposes five public modes: `design`, `build`, `preview`, `edit`, and `comment`.

#### Example

```typescript
const mode = await webflow.getCurrentMode();

if (mode === "design") {
  showDesignUI();
} else if (mode === "build") {
  showBuildUI();
} else {
  showNeutralUI();
}
```

To check a single mode without handling the full list, use `webflow.isMode()`:

```typescript
if (await webflow.isMode("design")) {
  await insertElement();
}
```

## Subscribing to mode changes

Use [`webflow.subscribe("currentappmode", callback)`](/designer/reference/user-changes-mode) to react to mode changes in real time.
The callback fires when the user switches modes, switches branches, or switches locales, and it receives an `AppModeChangeEvent` object with:

* `mode`: The new Designer mode name, or `null` when the internal state does not map to a public mode.
* `appModes`: The user's current capability booleans, keyed by capability name. The same object that the `webflow.canForAppMode()` method returns.

Callbacks that use the previous signature `() => void` continue to work.

#### Example

```typescript
const unsubscribe = webflow.subscribe("currentappmode", (event) => {
  console.log("New mode:", event.mode);

  if (event.appModes.canDesign) {
    showDesignTools();
  } else {
    hideDesignTools();
  }
});
```

## Choosing the right approach

The Designer API offers several patterns for mode awareness.
Use this table to decide which pattern fits your extension's needs:

| Approach                                        | When to use it                                                                                   |
| :---------------------------------------------- | :----------------------------------------------------------------------------------------------- |
| `webflow.canForAppMode()`                       | Check one or more capability booleans before a specific action.                                  |
| `webflow.getCurrentMode()`                      | Read the current Designer mode name on demand.                                                   |
| `webflow.isMode()`                              | Branch on a single mode without reading the full list.                                           |
| `webflow.subscribe("currentappmode", callback)` | React to mode, branch, or locale changes as they happen.                                         |
| `try/catch` with `ModeForbidden` or `Forbidden` | Recover from an action that was blocked because the current mode or permissions do not allow it. |

## Error handling for App modes

When the Designer API blocks an action, it throws one of two errors:

| Cause tag       | Meaning                                                                                    | User action                            |
| :-------------- | :----------------------------------------------------------------------------------------- | :------------------------------------- |
| `ModeForbidden` | The Designer is in the wrong mode for the operation.                                       | Switch to the required mode.           |
| `Forbidden`     | The user lacks permission for the operation, typically because of role, locale, or branch. | Check role, locale, and branch status. |

Proactively check before acting by combining [`webflow.isMode()`](/designer/reference/is-mode) or [`webflow.canForAppMode()`](/designer/reference/get-users-designer-capabilities) with a fallback `try/catch`:

```typescript
try {
  if (!(await webflow.isMode("design"))) {
    await webflow.notify({
      type: "Error",
      message: "Switch to Design mode to insert elements.",
    });
    return;
  }

  const el = await webflow.getSelectedElement();
  await el.append(webflow.elementPresets.DOM);
} catch (error) {
  switch (error.cause.tag) {
    case "ModeForbidden":
      await webflow.notify({
        type: "Error",
        message: error.message,
      });
      break;
    case "Forbidden":
      await webflow.notify({
        type: "Error",
        message: "Check that you are in the primary locale on the main branch with the required role.",
      });
      break;
    default:
      throw error;
  }
}
```

For a full list of error cause tags, see the [Error Handling](/designer/reference/error-handling) reference.

## Testing with App Modes

To test out how your Designer Extension will function with Expanded App Modes, you can opt-in to the feature with your `webflow.json` manifest file.

```json
// webflow.json manifest file
{
  "name": "my app",
  "apiVersion": "2",
  "featureFlags": {
    "expandedAppModes": true
  }
}
```

Now, if you launch your Designer Extension from the Apps Panel as you normally would today, you can switch to Build mode, as an example, and your App should remain open. If you take an action via your App that a user shouldn't be able to in that mode, you will see a `ModeForbidden` error thrown (or a `Forbidden` error when the permission gap is about role, locale, or branch), and you can catch the error appropriately to surface relevant user messaging.

## Opt Out

We recognize that for some Apps, it may take more time to incorporate code changes to add extra error handling, UI considerations, etc. with expanded App Modes. To opt-out, set the `expandedAppModes` feature flag to false in your `webflow.json` manifest file (see below). Then, simply create a new updated app bundle with this change and submit it for review.

```json
// webflow.json manifest file
{
  "name": "my app",
  "apiVersion": "2",
  "featureFlags": {
    "expandedAppModes": false
  }
}
```

### Deciding to Opt Out

Opting out of expanded App Modes means your App closes automatically when the user switches away from Design mode. The App continues to run while the user is in Design mode in the primary locale on the main branch.

## Designer v1 APIs

If you have an App using Designer v1 APIs, your app will not be able to be launched in other modes around the Designer, and will continue to only be launched when Designing in the canvas in the primary locale and main branch.