Automattic Design System

Components

InputControl

A complete input field with integrated label and description.

import { InputControl } from '@wordpress/ui';

View on Storybook

View source on GitHub

PropsPermalink to this section

NameDefaultDescription
details

ReactNode

Additional information about the field, which unlike a normal description, can include links and other semantic elements.

Do not use this prop when the content is only plain text; use description instead.

label Required

string

The accessible label. All controls must be labeled.

style

CSSProperties

CSS style to apply to the element.

disabled

boolean

Whether the field is disabled.

type

HTMLInputTypeAttribute | undefined

The type of the input element.

value

string | number | readonly string[] | undefined

The value to use in controlled mode.

defaultValue

string | number | readonly string[] | undefined

The default value to use in uncontrolled mode.

className

string

CSS class name to apply to the element.

prefix

ReactNode

Element to render before the input.

description

string

The accessible description, associated using aria-describedby.

For screen reader accessibility, this should only contain plain text, and no semantics such as links.

size

"default" | "compact"

The size of the field.

suffix

ReactNode

Element to render after the input.

render

ComponentRenderFn<HTMLAttributesWithRef<any>> | ReactElement<Record<string, unknown>, string | JSXElementConstructor<any>> | undefined

Replaces the component’s default HTML element using a given React element, or a function that returns a React element.

hideLabelFromVisionfalse

boolean

Whether to visually hide the label while keeping it accessible to screen readers.

onValueChange

(value: string, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void

Callback fired when the value changes. Use when controlled.

ExamplesPermalink to this section

DefaultPermalink to this section

const Default = () => <InputControl
    label="Label"
    description="This is the description."
    placeholder="Placeholder" />;

Visually Hidden LabelPermalink to this section

const VisuallyHiddenLabel = () => <InputControl hideLabelFromVision />;

With DetailsPermalink to this section

const WithDetails = () => <InputControl description={undefined} details={DETAILS_EXAMPLE} />;

With PrefixPermalink to this section

const WithPrefix = () => <InputControl ref={undefined} />;

With Suffix ControlPermalink to this section

const WithSuffixControl = () => <InputControl ref={undefined} />;

PasswordPermalink to this section

const Password = () => {
    const [ show, setShow ] = useState( false );

    return (
        <InputControl
            defaultValue="password"
            type={ show ? 'text' : 'password' }
            suffix={
                <InputLayout.Slot padding="minimal">
                    <IconButton
                        label={ show ? 'Hide password' : 'Show password' }
                        onClick={ () => setShow( ! show ) }
                        icon={ show ? unseen : seen }
                        size="small"
                        variant="minimal"
                    />
                </InputLayout.Slot>
            } />
    );
};

DatePermalink to this section

const Date = () => <InputControl type="date" />;

NumberPermalink to this section

const Number = () => <InputControl placeholder="0" type="number" />;

Number With SteppersPermalink to this section

const NumberWithSteppers = () => {
    const [ value, setValue ] = useState( 0 );

    return (
        <InputControl
            type="number"
            value={ value }
            onValueChange={ ( v ) => setValue( parseInt( v, 10 ) ) }
            suffix={
                <InputLayout.Slot padding="minimal">
                    <Stack direction="row" gap="xs">
                        <IconButton
                            label="Increment"
                            icon={ plus }
                            onClick={ () => setValue( value + 1 ) }
                            size="small"
                            variant="minimal"
                        />
                        <IconButton
                            label="Decrement"
                            icon={ reset }
                            onClick={ () => setValue( value - 1 ) }
                            size="small"
                            variant="minimal"
                        />
                    </Stack>
                </InputLayout.Slot>
            } />
    );
};

DisabledPermalink to this section

const Disabled = () => <InputControl disabled />;