DimensionControl Edit

DimensionControl DimensionControl

DimensionControl is a component designed to provide a UI to control spacing and/or dimensions.

Usage Usage

In a block’s edit implementation, render a <DimensionControl /> component.

import { registerBlockType } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';
import {
    DimensionControl,
} from '@wordpress/block-editor';

registerBlockType( 'my-plugin/my-block', {
    // ...

    attributes: {
        // other attributes here
        // ...

        paddingSize: {
            type: 'string',
        },
    },

    edit( { attributes, setAttributes, clientId } ) {

        const { paddingSize } = attributes;


        const updateSpacing = ( dimension, size, device = '' ) => {
            setAttributes( {
                [ `${ dimension }${ device }` ]: size,
            } );
        };

        return (
            <DimensionControl
                label={ __( 'Padding' ) }
                icon={ 'desktop' }
                onChange={ partialRight( updateSpacing, 'paddingSize' ) }
                value={ paddingSize }
            />
        );
    }
} );

Note: it is recommended to partially apply the value of the Block attribute to be updated (eg: paddingSize, marginSize…etc) to your callback functions. This avoids the need to unnecessarily couple the component to the Block attribute schema.

Note: by default, if you do not provide an initial value prop for the current dimension value, then no value will be selected (ie: there is no default dimension set).

Top ↑

Props Props

label label

  • Type: String
  • Default: undefined
  • Required: Yes

The human readable label for the control.

Top ↑

value value

  • Type: String
  • Default: ''
  • Required: No

The current value of the dimension UI control. If provided the UI with automatically select the value.

Top ↑

sizes sizes

  • Type: Array
  • Default: See packages/block-editor/src/components/dimension-control/sizes.js
  • Required: No

An optional array of size objects in the following shape:

[
    {
        name: __( 'Small' ),
        slug: 'small',
    },
        {
        name: __( 'Medium' ),
        slug: 'small',
    },
    // ...etc
]

By default a set of relative sizes (small, medium…etc) are provided. See packages/block-editor/src/components/dimension-control/sizes.js.

Top ↑

icon icon

  • Type: String
  • Default: undefined
  • Required: No

An optional dashicon to display before to the control label.

Top ↑

onChange onChange

  • Type: Function
  • Default: undefined
  • Required: No
  • Arguments::
    • size – a string representing the selected size (eg: medium)

A callback which is triggered when a spacing size value changes (is selected/clicked).

Top ↑

className className

  • Type: String
  • Default: ''
  • Required: No

A string of classes to be added to the control component.