Box & Grid - Site Builder v0.15.20: Active |
Box & Grid - Pronto Theme v0.1.11: Active |
Box & Grid - Site Builder Pro: Coming Soon |
Mon, Nov 9, 2026

Site Builder

SDK: v0.10.14

Build with Box & Grid®

Extend the Box & Grid – Site Builder ecosystem with custom widgets built using our public Box & Grid SDK.

The SDK provides a standardized framework for registering extensions, declaring widgets, configuring inspector controls, integrating dynamic content, and rendering your components consistently in both the visual builder and the published website.

Build independently of Box & Grid Pro using the SDK bundled with Site Builder Core.

Current SDK: v0.10.14 (Developer Preview)

Getting started: Create your first custom widget using the examples below, or download the complete sample extension to explore the implementation.

The SDK currently supports custom leaf widgets, standard inspector controls, responsive styling, dynamic-data integrations, and controlled frontend rendering. Third-party structural widgets and custom inspector-rendering APIs are not yet publicly supported.

Example SDK Widget Structure

1. Register an SDK extension

PHP

add_action( 'box_grid_sdk_ready', function ( $sdk ) {

    if (
        ! $sdk->supports( '0.10.14' ) ||
        ! $sdk->supports_box_grid( '0.15.27' )
    ) {
        return;
    }

    $extension = $sdk->register_extension( array(
        'id'              => 'example-notice-extension',
        'name'            => 'Example Notice Extension',
        'version'         => '0.1.1',
        'requiresSdk'     => '0.10.14',
        'requiresBoxGrid' => '0.15.27',
        'pluginFile'      => __FILE__,
    ) );

    if ( is_wp_error( $extension ) ) {
        return;
    }

    // Register widgets and renderers in subsequent SDK hooks.
} );

2. Declare a custom widget

PHP

add_action( 'box_grid_sdk_register_widgets', function ( $widgets ) {

    $widgets->register( 'example-notice-extension', array(
        'id'       => 'example_notice',
        'label'    => 'Example Notice',
        'category' => 'content',
        'contexts' => array( 'page', 'post', 'footer' ),

        'controls' => array(
            array(
                'key'     => 'message',
                'label'   => 'Message',
                'type'    => 'textarea',
                'section' => 'content',
                'default' => 'Hello from Box & Grid!',
            ),
            array(
                'key'     => 'showLabel',
                'label'   => 'Show Label',
                'type'    => 'yes_no_toggle',
                'section' => 'content',
                'default' => 'yes',
            ),
            array(
                'key'      => 'label',
                'label'    => 'Label',
                'type'     => 'text',
                'section'  => 'content',
                'default'  => 'Notice',
                'showWhen' => array(
                    'showLabel' => 'yes',
                ),
            ),
        ),

        'capabilities' => array(
            'structure'        => 'leaf',
            'responsiveStyles' => true,
        ),
    ) );
} );

3. Render the widget on the live website

PHP

add_action( 'box_grid_sdk_register_frontend_renderers', function ( $frontend ) {

    $frontend->register(
        'example-notice-extension',
        'example_notice',
        function ( $context ) {

            $message = $context->setting( 'message', 'Hello from Box & Grid!' );
            $label   = $context->setting( 'label', 'Notice' );
            $show    = $context->setting( 'showLabel', 'yes' );

            $html = '<div class="example-notice">';

            if ( 'yes' === $show ) {
                $html .= '<strong>' . esc_html( $label ) . '</strong>';
            }

            $html .= '<p>' . esc_html( $message ) . '</p>';
            $html .= '</div>';

            return $html;
        }
    );
} );

4. Render the same widget in the builder

JAVASCRIPT

(function (window) {
  'use strict';

  if (!window.BoxGridSDK?.editor) return;

  window.BoxGridSDK.editor.registerWidgetRenderer({
    id: 'example_notice',
    owner: 'example-notice-extension',

    renderPreview: function (context) {
      const settings = context.node?.settings || {};

      const message = settings.message ??
        'Hello from Box & Grid!';

      // Core escapes text returned in this format.
      return {
        text: String(message)
      };
    }
  });

})(window);

5. Style your widget

CSS

/* Shared structural styles for the Example Notice widget */

.bg-widget-example_notice .example-notice {
  box-sizing: border-box;
  min-width: 0;
}

.bg-widget-example_notice .example-notice-heading {
  display: block;
  font-weight: 700;
}

.bg-widget-example_notice .example-notice-message {
  margin: 0;
  overflow-wrap: anywhere;
}
PHP

add_action(
    'box_grid_sdk_register_frontend_assets',
    function ( $assets ) use ( $extension_id ) {

        $assets->register_shared_style(
            $extension_id,
            'example_notice',
            'bg-example-notice-style',
            plugins_url(
                'assets/notice.css',
                __FILE__
            ),
            array(),
            '0.1.1'
        );
    }
);

6A. Responsive controls

PHP

'styleTargets' => array(
    'heading' => 'Heading',
),

'controls' => array(

    // Retain your existing Content controls here.

    array(
        'key'      => 'headingColor',
        'label'    => 'Heading Color',
        'type'     => 'color',
        'section'  => 'typography',
        'storage'  => 'style',
        'styleKey' => 'color',
        'target'   => 'heading',
        'default'  => '#ff5333',
    ),

),

'capabilities' => array(
    'structure'        => 'leaf',
    'responsiveStyles' => true,
    'globalStyles'     => true,
    'customCss'        => true,
),

6B. Connect the Style Target

HTML

<div class="example-notice">
  <strong
    class="example-notice-heading"
    data-bg-sdk-target="heading"
  >
    Notice
  </strong>

  <p class="example-notice-message">
    Hello from the Box & Grid SDK.
  </p>
</div>

7A. Conditional controls

PHP

array(
    'key'     => 'showLabel',
    'label'   => 'Show Label',
    'type'    => 'yes_no_toggle',
    'section' => 'content',
    'default' => 'yes',
),

array(
    'key'      => 'label',
    'label'    => 'Label',
    'type'     => 'text',
    'section'  => 'content',
    'default'  => 'Notice',

    'showWhen' => array(
        'showLabel' => 'yes',
    ),
),

7B. Respect the setting in the frontend renderer

PHP

$show_label = 'yes' === (string) $context->setting(
    'showLabel',
    'yes'
);

$label = (string) $context->setting(
    'label',
    'Notice'
);

if ( $show_label ) {
    $html .= '<strong
        class="example-notice-heading"
        data-bg-sdk-target="heading">'
        . esc_html( $label )
        . '</strong>';
}

8. Download the complete example plugin