Webflow Designer Extension Development

Build extensions that run inside Webflow's Designer as iframes, interacting with the Designer API to manipulate elements, styles, pages, and more.

Quick Start Workflow

Prerequisite: Register your app in Webflow first — see references/register-app.md. You'll need a Workspace with Admin permissions.

1. Scaffold:

   npx create-webflow-extension@latest

   (interactive prompts for project name, package manager, linter)
2. Develop:

   cd <name> && pnpm dev

   (serves at localhost:1337; also works with npm/yarn/bun)
3. Test: Install app on test site via Workspace Settings > Apps & Integrations > Develop
4. Open: Press "E" in Designer to open app panel, launch extension
5. Build:

   pnpm build

   for deployment

CLI Options

npx create-webflow-extension@latest [project-name] [options]

Options:
  --pm <pnpm|npm|yarn|bun>           Package manager to use (default: pnpm)
  --linter <oxlint|biome|eslint>     Linter to use
  --skip-git                         Skip git initialization
  --skip-install                     Skip dependency installation
  --quiet                            Suppress output

Core API Patterns

Getting and Setting Elements

// Get selected element
const el = await webflow.getSelectedElement();

// Get all elements
const elements = await webflow.getAllElements();

// Select element programmatically
await webflow.setSelectedElement(element);

Inserting Elements

const selected = await webflow.getSelectedElement();
if (selected) {
  // Insert siblings
  await selected.after(webflow.elementPresets.DivBlock);
  await selected.before(webflow.elementPresets.Paragraph);
  
  // Insert children (if element supports children)
  if (selected.children) {
    await selected.append(webflow.elementPresets.Image);
    await selected.prepend(webflow.elementPresets.Heading);
  }
}

Styling Elements

// Create and apply style
const style = await webflow.createStyle("MyStyle");
await style.setProperty("background-color", "blue");
await style.setProperty("font-size", "16px");
await element.setStyles([style]);

// Responsive styling
await style.setProperties(
  { "font-size": "14px" },
  { breakpoint: "medium", pseudo: "hover" }
);

User Notifications

await webflow.notify({ type: 'Success', message: 'Element created!' });
await webflow.notify({ type: 'Error', message: 'Please select an element.' });

Element Presets

Common presets via

webflow.elementPresets

:

• Layout:

  DivBlock

  ,

  Section

  ,

  Container

  ,

  Grid

  ,

  VFlex

  ,

  HFlex

• Text:

  Paragraph

  ,

  Heading

  ,

  TextBlock

  ,

  RichText

• Media:

  Image

  ,

  Video

• Forms:

  FormForm

  ,

  FormInput

  ,

  FormButton

• Navigation:

  Link

  ,

  LinkBlock

  ,

  NavBar

• Custom:

  DOM

  (for custom HTML tags)

For elements without presets, use DOM element:

const custom = webflow.elementBuilder(webflow.elementPresets.DOM);
custom.setTag("section");
custom.setAttribute("class", "custom-section");

Breakpoints and Pseudo-States

Breakpoints:

"xxl"

|

"xl"

|

"large"

|

"main"

|

"medium"

|

"small"

|

"tiny"

Pseudo-states:

"hover"

|

"active"

|

"pressed"

|

"visited"

|

"focus"

|

"focus-visible"

|

"placeholder"

|

"first-child"

|

"last-child"

|

"nth-child(odd)"

|

"nth-child(even)"

Error Handling

try {
  const el = await webflow.getSelectedElement();
  await el.remove();
} catch (err) {
  switch (err.cause?.tag) {
    case 'ResourceMissing':
      await webflow.notify({ type: 'Error', message: 'Element not found' });
      break;
    case 'InvalidElementPlacement':
      await webflow.notify({ type: 'Error', message: 'Cannot place element here' });
      break;
    default:
      await webflow.notify({ type: 'Error', message: 'An error occurred' });
  }
}

Common error tags:

DuplicateValue

,

Forbidden

,

InternalError

,

InvalidElementPlacement

,

InvalidRequest

,

InvalidStyle

,

ResourceMissing

,

VariableInvalid

Project Structure

Generated by

create-webflow-extension

(React 19 + TypeScript + Rspack):

my-extension/
├── public/
│   └── index.html        # Entry point
├── src/
│   ├── App.tsx           # Main React component
│   ├── main.tsx          # React entry point
│   └── index.css         # Styles
├── webflow.json          # Extension settings
├── rspack.config.ts      # Rspack bundler configuration
├── package.json
└── tsconfig.json

Reference Documentation

Each reference file includes YAML frontmatter with

name

,

description

, and

tags

for searchability. Use the search script to find relevant references quickly:

# List all references with metadata
python scripts/search_references.py --list

# Search by tag (exact match)
python scripts/search_references.py --tag <tag>

# Search by keyword (across name, description, tags, and content)
python scripts/search_references.py --search <query>

Quick Lookup

• references/designer-apis-reference.md: All APIs and methods in one place (start here)

Detailed Guides

• references/create-webflow-extension-reference.md:

  create-webflow-extension

  scaffolding CLI
• references/webflow-cli-reference.md: Webflow CLI for serving, bundling, and listing extensions
• references/elements-api.md: Element manipulation and presets
• references/styles-api.md: Styling, breakpoints, pseudo-states
• references/components-api.md: Component definitions and instances
• references/pages-api.md: Page and folder management
• references/variables-api.md: Design variables and collections
• references/assets-api.md: Asset upload and management
• references/extension-utilities.md: Site info, events, notifications, app discovery, authentication
• references/error-handling.md: Error codes and handling patterns
• references/design-guidelines.md: UI design for native Webflow look
• references/register-app.md: Registering a Webflow App and configuring capabilities
• references/marketplace-guidelines.md: Marketplace review criteria (safety, technical, design, branding)
• references/app-submission-and-listing.md: Submitting your app and creating an effective listing
• references/faq.md: FAQ and troubleshooting for extensions, marketplace, and common issues

Scripts

• scripts/init-extension.sh

  : Quick project initialization wrapper around

  create-webflow-extension

• scripts/validate-extension.py

  : Validate extension structure before bundling

• scripts/search_references.py

  : Search reference files by tag, keyword, or list all with metadata

Assets

• assets/webflow-variables.css

  : CSS variables for Webflow's design system colors, typography, and shadows

Best Practices

1. Check element capabilities: Always verify

   element.children

   before append/prepend,

   element.textContent

   before text operations
2. Handle errors gracefully: Use try/catch with

   webflow.notify()

   for user feedback
3. Responsive design: Test on multiple breakpoints when setting styles
4. Use variables: Leverage Webflow's CSS variables for consistent theming
5. Subscribe to events: Use Designer events to keep extension state in sync
6. Appropriate sizing: Use

   webflow.resizeExtension()

   for proper panel dimensions