Color

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
description String Display a description below the label. No ā€“
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'),
            'description' => __('Select 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').