Docs/Advanced Topics/Validation

Validation

Every option field is sanitized on save based on its type, before it's written to theme_mods. You can replace that behavior per field.

Default sanitization by type

Type	What happens on save
`textarea` / `editor`	`wp_kses()` with an SVG-safe allow-list (see Hooks & Filters).
`switch`	Detected across every shape the value can arrive in (form token, bool, int), then normalized to `'on'/'off'` or `'true'/'false'` per `data_type`.
`checkbox`	Only an array is accepted; each value passes through `sanitize_text_field()`.
`select`	`sanitize_text_field()` (or per-item, if the value is an array).
`colorpicker`	Must match a hex (`#rgb`/`#rrggbb`/`#rrggbbaa`) or `rgb()`/`rgba()` pattern — anything else is discarded to an empty string.

Overriding it: sanitize_callback

Add a sanitize_callback key to any option field to fully replace its default sanitizer. Your callback receives the raw value and the field definition, and its return value is what gets saved:

PHP

[
    'id'    => 'support_email',
    'type'  => 'text',
    'label' => 'Support Email',
    'sanitize_callback' => function( $value, $field ) {
        return sanitize_email( $value );
    },
]

This is enforcement, not a validation message

There's no built-in "required field" error UI — a sanitize_callback silently coerces or discards an invalid value. If a user needs to see why a value was rejected, validate and message on your own admin screen, or check the saved value in a tpmeta/options/saved hook and act on it (log, notify, or overwrite).

Composite fields expect arrays, not strings

Repeater, gradient and multicolor fields store arrays. If you write a custom callback or sanitizer for a field type, guard with is_array() before treating the value as a string — see Best Practices.