How do I enable and use Windsurf Previews to iterate on a web UI inside the IDE?

Most teams ship frontends with a browser in one hand and the IDE in the other, copy‑pasting errors, HTML, and CSS back and forth. Windsurf Previews collapses that loop: you see your live web app directly inside the Windsurf Editor, click any element, and Cascade uses that exact context to reshape your UI—without leaving flow.

Quick Answer: Windsurf Previews lets you run and view your web app inside the IDE, then send specific elements or console errors to Cascade so it can propose and apply UI changes in context. You enable it from Cascade or the Website tools icon, and it works across HTML/React apps in both the in‑IDE panel and a Chromium‑based browser.

The Quick Overview

What It Is: Windsurf Previews is a live, in‑IDE web preview wired into Cascade. It mirrors your running app, lets you click elements, and sends them (and errors) into your Cascade conversation so you can iterate quickly on layout, styling, and behavior.
Who It Is For: Frontend and full‑stack developers working on web UIs—React, HTML, design systems—who want to iterate visually without bouncing between editor, browser, and chat tools.
Core Problem Solved: It removes the context‑switching and guesswork of traditional AI coding help. Instead of describing “that button on the right that’s too small,” you click it in the preview and Cascade edits the real code with lint‑clean changes.

How It Works

At a high level, Windsurf Previews hooks into your local dev server, streams the live page into Windsurf, and exposes a “send to Cascade” path from DOM elements and console errors. That context lands directly inside your Cascade thread, which is already tracking your edits, terminal commands, and conversation. Cascade then proposes code changes, auto‑lints them, and you stay in one continuous flow.

Here’s the flow broken into phases:

Enable & Start a Preview:
- Run your app locally (e.g., npm run dev, yarn dev, pnpm dev) using the Windsurf terminal, or ask Cascade to start it.
- Activate a Windsurf Preview from the Website tools icon above the Cascade input or by asking Cascade to “start a preview of my web app.”
- Choose where to show it: inside the IDE, or in a Chromium‑based browser (Chrome, Arc, etc.).
Send UI Context to Cascade:
- Interact with the preview like a normal browser.
- Click on HTML or React elements you want to tweak and send them to Cascade as context—no screenshots or copy‑paste required.
- When something breaks, send console errors from the preview directly into the Cascade thread.
Iterate on the UI in Flow:
- Ask Cascade for layout, styling, or behavior changes (“Make this card grid responsive,” “Align this button with the form fields”).
- Cascade updates the relevant files across your repo, auto‑lints its own changes, and you reload the preview—or let hot reload show the update immediately.
- Repeat: click, send, reshape, ship.

Features & Benefits Breakdown

Core Feature	What It Does	Primary Benefit
In‑IDE Live Web Preview	Renders your locally running web app inside Windsurf or a Chromium browser.	See your UI and code side‑by‑side; no constant window hopping.
Element & Error Context Sharing	Lets you send selected React/HTML elements and console errors to Cascade.	Cascade works with precise UI context, not vague descriptions.
Cascade‑Powered UI Iteration	Uses that context to propose multi‑file code changes and auto‑lint them.	Faster, lint‑clean UI changes from “See it” to “Ship it” in one loop.

Ideal Use Cases

Best for rapid UI iteration on design tweaks: Because you can click the exact card, button, or section in the preview, send it to Cascade, and say “match this to the Figma spec” or “increase contrast to meet AA,” then see the change live without leaving Windsurf.
Best for debugging layout or runtime issues: Because you can trigger the bug in the preview, send the console error to Cascade, and have it trace through your codebase to propose a fix, auto‑lint it, and let you re‑run the same scenario instantly.

Enabling Windsurf Previews

Windsurf Previews are available on all plans and cost no credits, but they’re opt‑in so you stay in control of your workflow.

Step 1: Make sure your app can run locally

Open your repo in the Windsurf Editor.
Start your dev server in the built‑in terminal, for example:
- npm run dev
- yarn dev
- pnpm dev
Confirm the app runs at a local URL (e.g., http://localhost:3000).

You can also simply ask Cascade:

“Start my web app and open a preview.”

Cascade will infer the right command from your project config and run it in the Windsurf terminal.

Step 2: Activate a Preview

You have two main ways to turn on Windsurf Previews:

From Cascade (conversational):
In your Cascade thread, say something like:
- “Start a Windsurf Preview of my app.”
- “Open a preview of the local dev server.”
Cascade will connect to your running app and open the preview panel.
From the Website tools icon (UI‑driven):
Above the Cascade input, look for the Website tools icon. Click it and choose the option to start a Windsurf Preview. This attaches the preview to your current Cascade conversation.

Step 3: Choose where to view the preview

Windsurf Previews can run:

Inside the IDE: As a panel within the Windsurf Editor—ideal for tight, one‑screen workflows.
In a separate browser: In Chrome, Arc, or another Chromium‑based browser, if you prefer a full browser window.

You can switch depending on your screen real estate and how you like to debug.

Step 4: Confirm or adjust settings

If you ever need to disable or tweak Previews:

Open Windsurf Settings inside the editor.
Look for the Windsurf Preview controls to turn it off/on or adjust behavior.

Using Windsurf Previews to Iterate on a Web UI Inside the IDE

Once your preview is running, you can treat it like a live, interactive canvas wired straight into Cascade.

Click elements to send them to Cascade

In the preview:

Hover and select the UI element you want to change—a button, card, nav item, modal, etc.
Use the UI affordance to send that element to Cascade.

Under the hood, Windsurf grabs the relevant HTML/React component representation and passes it into your Cascade conversation as structured context. You no longer need to:

Inspect the DOM, copy outerHTML, paste into chat.
Explain “the third card in the grid under the hero section.”

Now your prompt can be as simple as:

“For the element I just sent, make the text 16px, ensure 4px padding, and align the icon to the left.”

Cascade uses:

The element you sent,
Your current codebase context,
And your recent edits/commands

to propose changes in the right files (e.g., Card.tsx, Button.css, Tailwind classes, etc.).

Send console errors to Cascade

When something breaks:

Trigger the bug in the Windsurf Preview.
Look at the console errors.
Use the option to send the error directly to Cascade.

This gives Cascade:

The exact runtime stack trace,
The URL/route you’re on,
And your current code context.

Then you can ask:

“Fix this error and explain what’s going wrong.”

Cascade will:

Locate the failing code (often across multiple files).
Propose a fix.
Auto‑lint its own changes so you don’t inherit new lint failures.

You re‑run or refresh the preview, confirm the bug is gone, and keep shipping.

Guide Cascade with UI‑specific prompts

Because the preview keeps Cascade tightly grounded, you can use surprisingly natural prompts and expect precise edits, like:

“For the card grid I just sent, make it a 2‑column layout on mobile and 4 columns on desktop.”
“Increase contrast on this form to meet WCAG AA, but keep spacing consistent with the design system.”
“This header shifts on scroll; keep it sticky and avoid layout jank.”

Cascade will:

Update the relevant components/styles.
Auto‑lint those changes.
Let you verify immediately in the preview.

Features That Make Preview‑Driven UI Iteration Work

Even though this article focuses on Windsurf Previews, the experience is powered by other Windsurf primitives behind the scenes:

Cascade with flow awareness:
It tracks your edits, terminal commands, and now UI/context from Previews. This shared timeline is how it stays in sync with what you’re doing instead of making isolated guesses.
Auto‑linter:
After Cascade proposes changes (e.g., CSS in JS tweaks, React component updates), it auto‑lints its own diffs so you avoid the classic “AI broke the linter” problem.
Terminal integration:
If an error implies a missing dependency or misconfigured dev server, you can hit Cmd+I in the terminal and ask Cascade to fix your command, update scripts, or adjust environment variables—without leaving Windsurf.

Together with Previews, this is what turns UI iteration into a tight, repeatable loop:

See it.
Shape it.
Ship it.

All inside the editor.

Limitations & Considerations

Works with locally running web apps:
Windsurf Previews are built to attach to your local dev server. If your app isn’t running or is only available in a remote, locked‑down environment, you’ll need to adjust your setup (for example, running the dev server locally or via a secure tunnel) before using Previews.
Browser support is Chromium‑focused:
External previews are supported in Chrome, Arc, and other Chromium‑based browsers. If your workflow relies heavily on non‑Chromium browsers for testing, you can still use them—but Windsurf’s integrated preview is optimized around Chromium.

Pricing & Plans

Windsurf Previews are:

Available to all Windsurf plans.
Free in terms of credits—using Previews doesn’t consume additional credits beyond your normal Cascade usage.

In practice that looks like:

Individual / Pro‑style plans: Best for solo developers or small teams who want the full Windsurf Editor experience—including Previews, Cascade, and Tab—without worrying about preview‑metering.
Teams / Enterprise plans: Best for organizations that need everything above plus enterprise controls:
- Centralized billing, SSO, and RBAC
- Automated zero data retention (ZDR) by default for Teams/Enterprise
- Hybrid and Self‑hosted options for security‑sensitive environments

Previews work the same from a feature perspective; the main difference is the governance and deployment model around them.

Frequently Asked Questions

Do I need a special plugin or extension to use Windsurf Previews?

Short Answer: No. Windsurf Previews are built into the Windsurf Editor and available on all plans.

Details:
There’s nothing extra to install or configure beyond running your web app locally. Once your dev server is up, you can:

Ask Cascade to start a preview, or
Use the Website tools icon above the Cascade input.

Previews can be shown inside the IDE or in a supported browser, and you can toggle them in Windsurf Settings.

Does using Windsurf Previews cost additional credits or impact my plan?

Short Answer: No. Previews themselves cost no credits and are available on every plan.

Details:
Windsurf Previews are a core part of the Windsurf Editor experience. You can:

Start previews as often as you like,
Click and send elements to Cascade,
Forward console errors,

without worrying about a separate “preview meter.” Your plan still governs overall Cascade usage and enterprise controls (ZDR, SSO, Hybrid/Self‑hosted), but Previews are included across the board.

Summary

If you’ve ever described a UI bug to an AI tool and felt like shouting, “No, this button,” Windsurf Previews is the fix. It pulls your live web app into the Windsurf Editor, lets you click the exact element or error you care about, and hands that context to Cascade—backed by auto‑linting and full codebase awareness. You get a tight loop:

Run your app inside Windsurf.
See changes live in an in‑IDE preview or Chromium browser.
Click elements or errors to send them to Cascade.
Let Cascade reshape your UI while keeping your code lint‑clean.

You stay in flow, ship faster, and never copy‑paste HTML into chat again.

Next Step

Get Started