Unit Control – Native Custom Fields

PHP Field Configuration Reference

Unit

Use this config when fieldType is unit.

1) Base Parameters

Parameter	Required	Type	Default	Choices	Description
`fieldType`	Yes	`string`	`unit`	`unit`	Sets control type.
`name`	Yes	`string`			Sets control name. Use snake_case.
`fieldLabel`	Yes	`string`			Sets control label.
`default`	No	`string`			Sets control default value.
`required`	No	`bool`	`false`	`true`, `false`	Sets control required.
`disabled`	No	`bool`	`false`	`true`, `false`	Sets control disabled.
`hideLabelFromVision`	No	`bool`	`false`	`true`, `false`	Sets control hide label from vision.
`fieldHelpText`	No	`string`			Sets control help text.
`className`	No	`string`			Sets control css class name.
`fieldLabelPosition`	No	`string`	`top`	`top`, `left`	Sets control label position.
`fieldLabelTextTransform`	No	`string`	`uppercase`	`uppercase`, `capitalize`, `lowercase`	Sets control label text transform.

2) Unit Specific Parameters

Parameter	Required	Type	Default	Choices	Description
`size`	No	`string`	`default`	`default`, `small`	Adjusts the size of the input.
`disableUnits`	No	`bool`	`false`	`true`, `false`	If true, the unit selector is hidden.
`isPressEnterToChange`	No	`bool`	`false`	`true`, `false`	If true, the ENTER key press is required to trigger an onChange. A change is also triggered on blur.
`isResetValueOnUnitChange`	No	`bool`	`false`	`true`, `false`	If true, and the selected unit provides a default value, this value is set when changing units.
`isUnitSelectTabbable`	No	`bool`	`true`	`true`, `false`	Determines if the unit select is tabbable.

3) PHP Array Schema

Here is an example of how to use the unit control in a post meta configuration:

[
    'fieldType' => 'unit',
    'name' => 'post_unit',
    'fieldLabel' => 'Post Unit',
    'required' => false,
    'disabled' => false,
    'hideLabelFromVision' => false,
    'fieldHelpText' => 'Enter a value with unit.',
    'className' => 'custom-class',
    'fieldLabelPosition' => 'top',
    'fieldLabelTextTransform' => 'uppercase',
    'size' => 'default',
    'disableUnits' => false,
    'isPressEnterToChange' => false,
    'isResetValueOnUnitChange' => false,
    'isUnitSelectTabbable' => true,
]

3) Hook-Based Example (Post Meta Config)

It is available to use this control in post meta fields, term meta fields and user settings page and options page fields.

Available hooks:

native_custom_fields_post_meta_fields
native_custom_fields_term_meta_fields
native_custom_fields_user_meta_fields
native_custom_fields_options_page_fields

add_filter( 'native_custom_fields_post_meta_fields', function( array $configs ): array {
    $post_type = 'book';

    if ( ! isset( $configs[ $post_type ] ) || ! is_array( $configs[ $post_type ] ) ) {
        $configs[ $post_type ] = [
            'post_type' => $post_type,
            'sections'  => [],
        ];
    }

    $configs[ $post_type ]['sections'][] = [
        'meta_box_id'       => 'design_settings',
        'meta_box_title'    => 'Design Settings',
        'meta_box_context'  => 'side',
        'meta_box_priority' => 'default',
        'fields'            => [
            [
            'fieldType' => 'unit',
            'name' => 'post_unit',
            'fieldLabel' => 'Post Unit',
            'required' => false,
            'disabled' => false,
            'hideLabelFromVision' => false,
            'fieldHelpText' => 'Enter a value with unit.',
            'className' => 'custom-class',
            'fieldLabelPosition' => 'top',
            'fieldLabelTextTransform' => 'uppercase',
            'size' => 'default',
            'disableUnits' => false,
            'isPressEnterToChange' => false,
            'isResetValueOnUnitChange' => false,
            'isUnitSelectTabbable' => true,
            ],
        ],
    ];

    return $configs;
} );

4) Stored Value Type

Field Type	Meta Value Type
unit	string (value with unit, for example `"10px"`)