Building your first Wix app with Wix Blocks

Wix Blocks is the fastest way to build and publish a Wix app without managing servers, writing React code, or configuring a build pipeline. It combines a visual drag-and-drop editor with Velo (Wix's JavaScript coding environment) to let you create powerful widgets, dashboard panels and configuration interfaces. This lesson takes you from a blank Blocks project to a working app with a site widget, a settings panel, and API connectivity.

What is Wix Blocks and When to Use It

Wix Blocks is a browser-based development environment where you build apps visually. Think of it as the Wix Editor, but instead of building websites, you are building app components that other Wix users can install on their sites. Every element you create in Blocks becomes a reusable component that adapts to the site owner's theme, layout and content.

• Visual widget builder: Drag and drop UI elements to create your app's site-facing components
• Dashboard panel builder: Create settings and configuration screens for the site owner's admin area
• Velo integration: Write JavaScript/TypeScript code for logic, API calls and data handling
• Automatic responsiveness: Widgets automatically adapt to different screen sizes and Wix layouts
• Theme-aware design: Your widgets inherit the site owner's fonts, colours and styling by default
• Zero DevOps: No servers, no build tools, no deployment pipelines - Wix handles everything

Creating Your First Blocks App

Build a Wix Blocks app from scratch step by step

• Go to the Wix Developer Centre at dev.wix.com and click "Create New App". Select "Wix Blocks" as your development method. Name your app and click "Create App".
• The Wix Blocks editor opens with a blank canvas. On the left panel, you will see the component tree. On the right, the properties panel. At the bottom, the code editor.
• Click "Add Widget" to create your first site widget. This is the component that will appear on the site owner's published website. Give it a descriptive name like "SEO Score Display".
• From the "Add" panel (+ button), drag elements onto your widget canvas: text elements, buttons, images, containers, repeaters and more. Arrange them to create your widget's layout.
• Switch to the "Properties & Events" tab on the right panel to define the widget's configurable properties. These are the settings that site owners can customise when they add your widget to their page.

Building a Widget: Practical Example

Let us build a practical example: an SEO score display widget that shows the site owner's SEO health score, key metrics, and improvement suggestions. This demonstrates all the core Blocks concepts you need.

Step 1: Design the Widget Layout

• Add a Container element as the widget root - set it to full width with 16px padding
• Inside the container, add a Text element for the score title and a second Text element for the numeric score
• Add a Progress Bar element below to visually represent the score (0-100)
• Add a Repeater element for displaying individual metric rows (each with an icon, label and value)
• Style with the Wix Design System colours: use $color-5 for primary text, $color-10 for accents

Step 2: Define Widget Properties

Properties let site owners customise your widget. In the Properties panel, define the settings that should be configurable.

• Add a "Title" property (type: string, default: "Your SEO Score") - appears in the widget settings panel
• Add a "Show Details" property (type: boolean, default: true) - toggles the metrics repeater visibility
• Add a "Accent Colour" property (type: colour picker) - lets site owners match the accent to their brand
• Add a "Max Items" property (type: number, min: 1, max: 10, default: 5) - controls how many metrics to show

Step 3: Add Widget Code

The code editor at the bottom of the Blocks interface is where you add logic. The widget code runs in the site context and can access Wix APIs, fetch data, and respond to user interactions.

// Widget code (runs on the site)
$widget.onPropsChanged((oldProps, newProps) => {
  // Update UI when site owner changes properties
  if (newProps.title !== oldProps.title) {
    $w('#titleText').text = newProps.title;
  }
  if (newProps.showDetails !== oldProps.showDetails) {
    $w('#metricsRepeater').collapsed = !newProps.showDetails;
  }
});

$w.onReady(async () => {
  // Set initial values from properties
  $w('#titleText').text = $widget.props.title;
  $w('#metricsRepeater').collapsed = !$widget.props.showDetails;

  // Fetch SEO data (example using an HTTP function)
  try {
    const response = await fetch('https://your-api.com/seo-score', {
      method: 'POST',
      body: JSON.stringify({ siteUrl: window.location.hostname }),
    });
    const data = await response.json();

    $w('#scoreText').text = String(data.score);
    $w('#progressBar').value = data.score;

    // Populate the metrics repeater
    $w('#metricsRepeater').data = data.metrics.slice(0, $widget.props.maxItems);
    $w('#metricsRepeater').onItemReady(($item, itemData) => {
      $item('#metricLabel').text = itemData.label;
      $item('#metricValue').text = itemData.value;
    });
  } catch (error) {
    $w('#scoreText').text = '--';
    $w('#progressBar').value = 0;
  }
});

Creating a Dashboard Panel

Dashboard panels appear in the site owner's Wix admin area. They provide app settings, analytics and management interfaces. In Blocks, dashboard panels are created separately from site widgets.

Add a dashboard panel to your Blocks app

• In the Blocks editor, click "Add Dashboard Page" from the app components list on the left.
• Design the dashboard layout using form elements: text inputs, dropdowns, toggles and buttons. This is where site owners configure your app.
• Add a "Save Settings" button that stores configuration to the Wix database using wix-data API.
• Connect the dashboard to your widget using the Wix Pub/Sub API or shared data collections so that settings changes propagate to the site widget.
• Test the dashboard by previewing it in the Blocks editor or deploying to your test site.

Design Presets and Responsive Layouts

Wix Blocks widgets must work across thousands of different site designs. You achieve this through design presets and responsive layout settings.

• Design presets: Create multiple visual variations of your widget (Light, Dark, Minimal, Bold) that site owners can choose from when adding the widget
• Responsive breakpoints: Define how your widget layout changes across desktop (>960px), tablet (760-960px) and mobile (<760px) viewports
• Use the Wix Design System tokens ($color-5, $color-10, etc.) instead of hard-coded colours so your widget automatically matches the site theme
• Set minimum and maximum widget dimensions to prevent layout breaking when users resize
• Test every design preset at every breakpoint before submitting - Wix reviewers check this thoroughly

Connecting Blocks Apps to Wix APIs

Blocks apps can access the full range of Wix APIs through Velo. This includes Wix Data, Wix CRM, Wix Stores, Wix Bookings, Wix Members and more.

// Backend code in Blocks (runs server-side)
import wixData from 'wix-data';

export async function getAppSettings(siteId) {
  const result = await wixData.query('AppSettings')
    .eq('siteId', siteId)
    .find();

  return result.items.length > 0
    ? result.items[0]
    : { siteId, score: 0, lastChecked: null };
}

export async function saveAppSettings(settings) {
  const existing = await wixData.query('AppSettings')
    .eq('siteId', settings.siteId)
    .find();

  if (existing.items.length > 0) {
    return wixData.update('AppSettings', {
      ...existing.items[0],
      ...settings
    });
  }
  return wixData.insert('AppSettings', settings);
}