sanitize_html_class() – Function | Developer.WordPress.org

Sanitizes an HTML classname to ensure it only contains valid characters.

Description

Strips the string down to A-Z,a-z,0-9,_,-. If this results in an empty string then it will return the alternative value supplied.

Parameters

$classnamestringrequired: The classname to be sanitized.
$fallbackstringoptional: The value to return if the sanitization ends up as an empty string.

Default:''

Return

string The sanitized value.

Source

function sanitize_html_class( $classname, $fallback = '' ) {
	// Strip out any percent-encoded characters.
	$sanitized = preg_replace( '|%[a-fA-F0-9][a-fA-F0-9]|', '', $classname );

	// Limit to A-Z, a-z, 0-9, '_', '-'.
	$sanitized = preg_replace( '/[^A-Za-z0-9_-]/', '', $sanitized );

	if ( '' === $sanitized && $fallback ) {
		return sanitize_html_class( $fallback );
	}
	/**
	 * Filters a sanitized HTML class string.
	 *
	 * @since 2.8.0
	 *
	 * @param string $sanitized The sanitized HTML class.
	 * @param string $classname HTML class before sanitization.
	 * @param string $fallback  The fallback string.
	 */
	return apply_filters( 'sanitize_html_class', $sanitized, $classname, $fallback );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘sanitize_html_class’, string $sanitized, string $classname, string $fallback ): Filters a sanitized HTML class string.

Uses	Description
sanitize_html_class()`wp-includes/formatting.php`	Sanitizes an HTML classname to ensure it only contains valid characters.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.

Used by	Description
WP_Media_List_Table::column_title()`wp-admin/includes/class-wp-media-list-table.php`	Handles the title column output.
_navigation_markup()`wp-includes/link-template.php`	Wraps passed links in navigational markup.
login_header()`wp-login.php`	Outputs the login page header.
WP_Screen::add_help_tab()`wp-admin/includes/class-wp-screen.php`	Adds a help tab to the contextual help for the screen.
WP_Plugin_Install_List_Table::display_rows()`wp-admin/includes/class-wp-plugin-install-list-table.php`	Generates the list table rows.
iframe_header()`wp-admin/includes/template.php`	Generic Iframe header for use with Thickbox.
attachment_submitbox_metadata()`wp-admin/includes/media.php`	Displays non-editable attachment metadata in the publish meta box.
_wp_menu_output()`wp-admin/menu-header.php`	Display menu.
sanitize_html_class()`wp-includes/formatting.php`	Sanitizes an HTML classname to ensure it only contains valid characters.
get_post_class()`wp-includes/post-template.php`	Retrieves an array of the class names for the post container element.
get_body_class()`wp-includes/post-template.php`	Retrieves an array of the class names for the body element.
get_comment_class()`wp-includes/comment-template.php`	Returns the classes for the comment div as an array.
_WP_Editors::editor_settings()`wp-includes/class-wp-editor.php`

Show 8 more Show less

Changelog

Version	Description
2.8.0	Introduced.

User Contributed Notes

Skip to note 6 content

elnico 6 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note

Class names must not start with numbers and this function does not take this into acount.
https://www.w3.org/TR/CSS21/syndata.html#characters
This function may return a string starting with digits which by W3 definition are not valid class names.
- In addition to not starting with numbers, class names MAY start with a dash (-) but ONLY if it is followed by a non-numeric character (so, dash followed by numbers or by itself is invalid). I wrote this filter to do additional checks on class names: add_filter( 'sanitize_html_class', function( string $sanitized, string $original, string $fallback, ): string { return preg_replace('#^(-([0-9]+|$)|[0-9]+)#', '', $sanitized) ?: $fallback; }, 10, 3, );
  
  wbeaumo 3 weeks ago
Log in to add feedback

lieutenantdan 8 years ago

Created this function to help escape multiple HTML classes, you can give it an array of classes or a string of them separated by a delimiter:

if( ! function_exists("sanitize_html_classes") ){
    function sanitize_html_classes($classes, $sep = " "){
        $return = "";

        if(!is_array($classes)) {
            $classes = explode($sep, $classes);
        }

        if(!empty($classes)){
            foreach($classes as $class){
                $return .= sanitize_html_class($class) . " ";
            }
        }

        return $return;
    }
}

Codex 9 years ago

Basic Example

<?php
// If you want to explicitly style a post, you can use the sanitized version of the post title as a class
$post_class = sanitize_html_class( $post->post_title );
echo '<div class="' . $post_class . '">';
?>

Mahdi Yazdani 5 years ago

Sanitize multiple HTML classes in one pass.

Accepts either an array of $classes, or a space-separated string of class names and runs them to sanitize using the sanitize_html_class function.

/**
 * Sanitize multiple HTML classes in one pass.
 *
 * @param    array  $classes           Classes to be sanitized.
 * @param    string $return_format     The return format, 'input', 'string', or 'array'.
 * @return   array|string
 */
function prefix_sanitize_html_classes( $classes, $return_format = 'input' ) {
	if ( 'input' === $return_format ) {
		$return_format = is_array( $classes ) ? 'array' : 'string';
	}

	$classes           = is_array( $classes ) ? $classes : explode( ' ', $classes );
	$sanitized_classes = array_map( 'sanitize_html_class', $classes );

	if ( 'array' === $return_format ) {
		return $sanitized_classes;
	} else {
		return implode( ' ', $sanitized_classes );
	}
}

Skip to note 10 content

wbeaumo 3 weeks ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

As was previously mentioned, this function does not take into account that class names may not start with numbers. Class names MAY start with a dash (-) but ONLY if it is followed by a non-numeric character (so, dash followed by numbers or by itself is invalid). I wrote this filter to do additional checks on class names:

add_filter( 'sanitize_html_class', function( string $sanitized, string $original, string $fallback, ): string { return preg_replace('#^(-([0-9]+|$)|[0-9]+)#', '', $sanitized) ?: $fallback; }, 10, 3, );

(Apologies for the repeat comment, I did not realize that responding to someone else’s message would mean my response doesn’t show by default, nor did I realize that it would mangle my code’s whitespace. I don’t know how to delete my earlier comment.)

Log in to add feedback

sanitize_html_class( string $classname, string $fallback = '' ): string

In this article