Control help text in WordPress block

WordPress control components like SelectControl supports the help prop. It is used to generate help text for the respective control element.

Help text

The help prop, when added to a component like SelectControl , generates a help text using the help property's value as the content. This text is usually displayed near the control element, often below it, to provide additional information or guidance to the person regarding the use of the control.

I believe that help text, in most cases, should be used in block’s control components because it serves as a guide to people.

It explains what the control does or clarifies the kind of input required. Help text can also provide examples of valid input or additional explanations regarding the control's purpose or effect.

<RadioControl
	label={__("Filter Options", "sortable")}
	help={__(
		"Select 'All Entries' to show all, or 'Specific Date' to display based on a specific date.",
		"sortable",
	)}
	options={[
		{
			label: __("All Entries", "sortable"),
			value: "",
		},
		{
			label: __("Specific Date", "sortable"),
			value: "date",
		},
	]}
	selected={attributes.filter.displayType || ""}
	onChange={(value) => {
		...
	}}
/>

Above, code example from Sortable block for creating a control with two radio buttons: "All Entries" and "Specific Date." This control is used to filter entries either by a specific date or to show all entries without filtering.

The help prop in the code gives extra text to guide people on how to use the radio buttons, making it easier for them to know what to do.

Here's how it works:

1. The text "Select 'All Entries' to show all, or 'Specific Date' to display from a specific date." is set as the content of the help prop. This text is meant to guide the the person on what each radio button option does.
2. The "sortable" argument is a text domain which is a mechanism used in WordPress to handle text translation for internationalization. It helps to categorize translatable strings to manage translations.
3. The __() function is a part of WordPress's internationalization utilities, which is used to translate and retrieve the translated string. It takes two arguments: the text to be translated and the text domain.

Dynamic help text

Dynamic help text changes according to the option person selects, giving more useful advice based on selected choice.

<SelectControl
    label={__("Date Filter Type", "sortable")}
    value={attributes.filter.dateFilterType}
    options={[
        { label: __("On a Specific Date", "sortable"), value: "" },
        {
            label: __("Before a Specific Date", "sortable"),
            value: "before",
        },
        {
            label: __("After a Specific Date", "sortable"),
            value: "after",
        },
    ]}
    onChange={(value) =>
        ...
    }
    help={
        attributes.filter.dateFilterType === "before"
            ? __(
                    "Display entries that occur before the selected filter date below.",
                    "sortable",
              )
            : attributes.filter.dateFilterType === "after"
            ? __(
                    "Display entries that occur after the selected filter date below.",
                    "sortable",
              )
            : __(
                    "Display entries that occur on the selected filter date below.",
                    "sortable",
              )
    }
/>

In the given code example, the help prop of the <SelectControl> component is set dynamically based on the selected dateFilterType.

The help prop's value is determined by a ternary expression that checks the value of attributes.filter.dateFilterType. Depending on whether the value is "before", "after", or neither (an empty string "" for "On a Specific Date"), different help text is displayed.

This way, people get specific instructions related to their current selection, making the interface more intuitive and user-friendly.

Alternative approach

An alternative method to setting dynamic help text is to define a function that returns the help text based on the current state, and then pass this function to the help prop.

// Helper function.
function getHelpText(dateFilterType) {
    switch (dateFilterType) {
        case "before":
            return __("Display entries that occur before the selected filter date below.", "sortable");
        case "after":
            return __("Display entries that occur after the selected filter date below.", "sortable");
        default:
            return __("Display entries that occur on the selected filter date below.", "sortable");
    }
}

// Usage in SelectControl component.
<SelectControl
    ...
    help={getHelpText(attributes.filter.dateFilterType)}
/>

The function-based approach is cleaner and more scalable when dealing with multiple conditions, while the ternary approach is more concise for simpler, binary conditions.