Initial Setup

Element Studio needs somewhere to put your elements. Out of the box the only choices it
offers are Breakdance's own plugin folders, and anything saved there is destroyed by the next
plugin update. So the first thing to do — before you build a single element — is create a
small plugin of your own and register it as a saving location.

The official Breakdance Custom Elements starter plugin registers saving locations for elements, macros, and presets.

Install the Starter Plugin

1. Open the starter repository, choose Code > Download ZIP, and extract it.
2. Edit plugin.php: customize the plugin name, URI, description, and author. Replace BreakdanceCustomElements in the namespace and all three saving-location registrations with your own unique namespace; update their display labels too.
3. Zip the plugin folder, then open Plugins > Add New Plugin > Upload Plugin in WordPress. Install the ZIP and activate the plugin.
4. Reload Breakdance, open Element Studio, choose New element, and select your custom saving location. Add controls and save the element into your plugin.

See the WordPress Plugin Handbook for general plugin structure. The following scaffold is the equivalent setup if you prefer to create the plugin files yourself.

1. Create the plugin

Make a folder in wp-content/plugins/ — my-breakdance-elements/ in this example — with a
single plugin.php inside it:

<?php

/**
 * Plugin Name: My Breakdance Elements
 * Description: Custom elements built with Element Studio.
 * Author: Your Name
 * License: GPLv2
 * Version: 0.0.1
 */

namespace MyBreakdanceElements;

use function BreakdanceUtilgetDirectoryPathRelativeToPluginFolder;

add_action('breakdance_loaded', function () {
    BreakdanceElementStudioregisterSaveLocation(
        getDirectoryPathRelativeToPluginFolder(__DIR__) . '/elements',
        'MyBreakdanceElements',
        'element',
        'My Elements',
        false
    );

    BreakdanceElementStudioregisterSaveLocation(
        getDirectoryPathRelativeToPluginFolder(__DIR__) . '/macros',
        'MyBreakdanceElements',
        'macro',
        'My Macros',
        false
    );

    BreakdanceElementStudioregisterSaveLocation(
        getDirectoryPathRelativeToPluginFolder(__DIR__) . '/presets',
        'MyBreakdanceElements',
        'preset',
        'My Presets',
        false
    );
}, 9);

Create the three empty folders next to it — elements/, macros/, presets/ — then
activate the plugin from Plugins in wp-admin.

2. Reload the builder

Close and reopen the builder, then open Element Studio and click New element. My
Elements is now one of the saving locations, and everything you build there is yours.

What each argument does

registerSaveLocation($directoryPath, $namespace, $type, $label, $onlyForAdvancedUsers);

$directoryPath — the folder, relative to wp-content/plugins/. Not an absolute
path, which is why the example uses getDirectoryPathRelativeToPluginFolder(__DIR__)
rather than __DIR__ alone.

$namespace — the PHP namespace your generated element classes are written into. It
has to be unique on the site: it becomes the first half of every element slug your plugin
produces (MyBreakdanceElementsTestimonialCard), and two plugins claiming the same namespace
will collide. Use something derived from your own or your agency's name — never
EssentialElements or OxygenElements, which belong to the first-party element libraries.

$type — 'element', 'macro' or 'preset'. One call per type; a folder registered
as 'element' will not accept macros.

$label — what appears in the "Select a saving location" list when you create
something. Make it recognisable, because that list is the only thing standing between your
work and a first-party folder.

$onlyForAdvancedUsers — pass false. Breakdance's own locations pass true, which is
how they mark themselves as places ordinary users shouldn't be saving into.

Why the priority matters

The 9 at the end of the add_action call is not decoration. Breakdance loads element class
files on breakdance_loaded at the default priority of 10, by scanning every registered
saving location. Register your location any later than that and the scan has already run:
your folder is skipped, and your elements simply don't exist until the next page load.

Anything below 10 works. Breakdance's own element library registers at priority 5.

Keep it in git

Element Studio writes real files, and its Delete button removes them with no undo. The
sane workflow is a git repository at the root of your plugin folder:

cd wp-content/plugins/my-breakdance-elements
git init
git add .
git commit -m "Element plugin scaffold"

Commit after each element you finish. Beyond the safety net, this is also how you move
elements between sites — the plugin folder is the deliverable. Clone it into another
Breakdance install's wp-content/plugins/, activate it, and every element comes with it.

Where your files end up

Creating an element called "Testimonial Card" in this plugin produces:

wp-content/plugins/my-breakdance-elements/elements/Testimonial_Card/
├── element.php
├── html.twig
├── css.twig
└── default.css

Breakdance finds elements by globbing <saving location>/*/*.php, so every element needs its
own subfolder — which is what the studio creates. Files named ssr.php are skipped by that
scan on purpose; they're loaded at render time instead, which is what makes
server-side rendering work.

Fork and Distribute Your Plugin

You can also fork the starter repository on GitHub, rename it for your project, edit and commit the plugin details, then clone it into wp-content/plugins/. Commit local changes and push them to your fork using Git, GitHub CLI, or your editor's Git interface. The plugin folder contains the elements you can move between sites, share, or sell.