Color - Documentation

Description

The color field type creates an input field in the admin panel for selecting colors. It is rendered as an HTML <input type="color"> element styled with Bootstrap’s form-control class, typically providing a native browser color picker. This field is ideal for capturing color values, such as theme colors or design preferences, stored in hexadecimal format (e.g., #ff0000).

Available Options

Parameter	Type	Description	Required	Default
`name`	String	The name of the field, used as the identifier and default label if `label` is not provided.	Yes	–
`type`	String	The field type. Must be set to `color`.	Yes	–
`label`	String	The display label for the color field. If not provided, the `name` is used.	No	`name`
`placeholder`	String	A hint displayed in the field when it is empty, guiding the user on expected input.	No	`name`
`default`	String/Boolean	The default color value in hexadecimal format (e.g., `#ff0000`). If set to `false`, the field defaults to `#000000` in most browsers.	No	`false`
`class`	String	Additional CSS classes to apply to the color input for custom styling or JavaScript targeting.	No	–
`help`	String	A help message displayed in a sidebar or tooltip when the user clicks the info icon next to the field.	No	–
`required`	Boolean	If `true`, the field is marked as required, adding the HTML `required` attribute. Note that browsers typically enforce a valid hex color.	No	`false`

Note: The color field is stored in the settings array as a sanitized string in hexadecimal format (e.g., #ff0000), using WordPress’s sanitize_hex_color function, which ensures a valid color value or returns an empty string if invalid.

Example

Below is an example of how to define a color field in the $fields array for the Reusable Admin Panel settings class.

$this->fields = array(
    'general' => array(
        array(
            'name'    => __('Theme Color', 'your-plugin-slug'),
            'type'    => 'color',
            'label'   => __('Primary Theme Color', 'your-plugin-slug'),
            'default' => '#ff0000',
            'class'   => 'theme-color-input',
            'help'    => __('Select the primary color for the theme.', 'your-plugin-slug'),
            'required' => true
        )
    )
);

This configuration will create a color field labeled “Primary Theme Color” under the “general” section. It will default to #ff0000 (red), include the CSS class theme-color-input, display a help message, and be marked as required.

Usage Notes

The color field uses WordPress’s sanitize_hex_color for sanitization, ensuring the input is a valid hexadecimal color (3 or 6 digits, with a leading #). Invalid inputs are sanitized to an empty string.
The field’s ID is automatically generated as {section}-{name}, where name is sanitized using sanitize_title.
The field is styled using Bootstrap’s form-control class, though the native color picker appearance varies by browser. Custom styles can be applied via the class parameter.
The required attribute ensures a color is selected, triggering browser validation. Since browsers typically enforce valid hex colors, this is rarely an issue.
The type="color" attribute enables native browser color pickers on supported devices, falling back to a text input on others.
To retrieve the value of a color field, use the get_option method, e.g., $this->get_option('general', 'theme-color').