UnitControl Edit

This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.

UnitControl allows the user to set a value as well as a unit (e.g. px).

Usage Usage

import { __experimentalUnitControl as UnitControl } from '@wordpress/components';
import { useState } from '@wordpress/element';

const Example = () => {
    const [ value, setValue ] = useState( '10px' );

    return <UnitControl onChange={ setValue } value={ value } />;
};

Top ↑

Props Props

disableUnits: boolean disableUnits: boolean

If true, the unit <select> is hidden.

  • Required: No
  • Default: false

Top ↑

isPressEnterToChange: boolean isPressEnterToChange: boolean

If true, the ENTER key press is required in order to trigger an onChange. If enabled, a change is also triggered when tabbing away (onBlur).

  • Required: No
  • Default: false

Top ↑

isResetValueOnUnitChange: boolean isResetValueOnUnitChange: boolean

If true, and the selected unit provides a default value, this value is set when changing units.

  • Required: No
  • Default: false

Top ↑

isUnitSelectTabbable: boolean isUnitSelectTabbable: boolean

Determines if the unit <select> is tabbable.

  • Required: No
  • Default: true

Top ↑

label: string label: string

If this property is added, a label will be generated using label property as the content.

  • Required: No

Top ↑

labelPosition: string labelPosition: string

The position of the label (top, side, bottom, or edge).

  • Required: No

Top ↑

onChange: UnitControlOnChangeCallback onChange: UnitControlOnChangeCallback

Callback when the value changes.

  • Required: No
  • Default: noop

Top ↑

onUnitChange: UnitControlOnChangeCallback onUnitChange: UnitControlOnChangeCallback

Callback when the unit changes.

  • Required: No
  • Default: noop

Top ↑

size: string size: string

Adjusts the size of the input.
Sizes include: default, small

  • Required: No
  • Default: default

Top ↑

unit: string unit: string

Deprecated: Current unit value.
Instead, provide a unit with a value through the value prop.

Example:

<UnitControl value="50%" />
  • Required: No

Top ↑

units: WPUnitControlUnitList units: WPUnitControlUnitList

Collection of available units.

  • Required: No

Example:

import { __experimentalUnitControl as UnitControl } from '@wordpress/components';
import { useState } from '@wordpress/element';

const Example = () => {
    const [ value, setValue ] = useState( '10px' );

    const units = [
        { value: 'px', label: 'px', default: 0 },
        { value: '%', label: '%', default: 10 },
        { value: 'em', label: 'em', default: 0 },
    ];

    return <UnitControl onChange={ setValue } value={ value } units={units} />;
};

A default value (in the example above, 10 for %), if defined, is set as the new value when a unit changes. This is helpful in scenarios where changing a unit may cause drastic results, such as changing from px to vh.

Top ↑

value: number | string value: number | string

Current value. If passed as a string, the current unit will be inferred from this value.
For example, a value of 50% will set the current unit to %.

Example:

<UnitControl value="50%" />
  • Required: No