BoxControl Edit

BoxControl components let users set values for Top, Right, Bottom, and Left. This can be used as an input control for values like padding or margin.

Usage Usage

import { __experimentalBoxControl as BoxControl } from '@wordpress/components';
import { useState } from '@wordpress/element';

const Example = () => {
    const [ values, setValues ] = useState( {
        top: '50px',
        left: '10%',
        right: '10%',
        bottom: '50px',
    } );

    return (
        <BoxControl
            values={ values }
            onChange={ ( nextValues ) => setValues( nextValues ) }
        />
    );
};

Visualizer Visualizer

BoxControl provides a companion component that visually renders value changes. Place the component you would like the sides visualized within the companion <Visualizer> component.

import { __experimentalBoxControl as BoxControl } from '@wordpress/components';
import { useState } from '@wordpress/element';

import MyComponent from './my-component';

const { Visualizer } = BoxControl;

const Example = () => {
    const [ values, setValues ] = useState( {
        top: '50px',
        left: '10%',
        right: '10%',
        bottom: '50px',
    } );

    return (
        <>
            <BoxControl
                values={ values }
                onChange={ ( nextValues ) => setValues( nextValues ) }
            />
            <Visualizer>
                <MyComponent />
            </Visualizer>
        </>
    );
};

Alternatively, the <Visualizer> can be nested as a sibling to the component you would like visualized. Using <Visualizer /> in this manner will require the parent element having a position style.

import { __experimentalBoxControl as BoxControl } from '@wordpress/components';
import { useState } from '@wordpress/element';

import MyComponent from './my-component';

const { Visualizer } = BoxControl;

const Example = () => {
    const [ values, setValues ] = useState( {
        top: '50px',
        left: '10%',
        right: '10%',
        bottom: '50px',
    } );

    return (
        <>
            <BoxControl
                values={ values }
                onChange={ ( nextValues ) => setValues( nextValues ) }
            />
            <div style={ { position: 'relative' } }>
                <Visualizer />
                <MyComponent />
            </div>
        </>
    );
};

Top ↑

Props Props

Top ↑

inputProps inputProps

Props for the internal InputControl components.

  • Type: Object
  • Required: No

Top ↑

label label

Heading label for BoxControl.

  • Type: String
  • Required: No
  • Default: Box Control

Top ↑

onChange onChange

A callback function when an input value changes.

  • Type: Function
  • Required: Yes

Top ↑

onChangeShowVisualizer onChangeShowVisualizer

A callback function for visualizer changes, based on input hover interactions.

  • Type: Function
  • Required: Yes

Top ↑

units units

Collection of available units which are compatible with UnitControl.

  • Type: Array<Object>
  • Required: No

Top ↑

values values

The top, right, bottom, and left box dimension values.

  • Type: Object
  • Required: No