get_search_form() │ WP 2.7.0

Display search form.

Will first attempt to locate the searchform.php file in either the child or the parent, then load it. If it doesn't exist, then the default search form will be displayed. The default search form is HTML, which will be displayed. There is a filter applied to the search form HTML in order to edit or replace it. The filter is get_search_form.

This function is primarily used by themes which want to hardcode the search form into the sidebar and also by the search widget in WordPress.

There is also an action that is called whenever the function is run called, pre_get_search_form. This can be useful for outputting JavaScript that the search relies on or various formatting that applies to the beginning of the search. To give a few examples of what it can be used for.

Hooks from the function

pre_get_search_form

search_form_args

search_form_format

get_search_form

Return

null|String. Void if 'echo' argument is true, search form HTML if 'echo' is false.

Usage

get_search_form( $args );

$args(array)

Array of display arguments.

Default: array()

echo(true|false)
Whether to echo or return the form.
Default: true
aria_label(string)
ARIA label for the search form. Useful to distinguish multiple search forms on the same page and improve accessibility.
Default: ''

Examples

#1 Default HTML search forms

If there is no searchform.php file in the theme, calling this function will display the default HTML form:

<form role="search" method="get" id="searchform" class="searchform" action="<?php echo esc_url( home_url( '/' ) ); ?>">
	<div>
		<label class="screen-reader-text" for="s"><?php _x( 'Search for:', 'label' ); ?></label>
		<input type="text" value="<?php echo get_search_query(); ?>" name="s" id="s" />
		<input type="submit" id="searchsubmit" value="<?php echo esc_attr_x( 'Search', 'submit button' ); ?>" />
	</div>
</form>

This HTML tag will be output if html5 support is NOT set in the theme. Let me remind you, it is set through function add_theme_support() as follows:

// Add HTML5 theme support.
add_action( 'after_setup_theme', 'wp_kama_after_setup_theme' );

function wp_kama_after_setup_theme() {
	add_theme_support( 'html5', [ 'search-form' ] );
}

However, if html5 support is enabled, by default we get this HTML code for the search form:

<form role="search" method="get" class="search-form" action="<?php echo home_url( '/' ); ?>">
	<label>
		<span class="screen-reader-text"><?php echo _x( 'Search for:', 'label' ) ?></span>
		<input type="search" class="search-field" 
			placeholder="<?php echo esc_attr_x( 'Search …', 'placeholder' ) ?>" 
			value="<?php echo get_search_query() ?>" 
			name="s" 
			title="<?php echo esc_attr_x( 'Search for:', 'label' ) ?>" 
		/>
	</label>
	<input type="submit" class="search-submit" value="<?php echo esc_attr_x( 'Search', 'submit button' ) ?>" />
</form>

That is, the field type changes from text to search: type="search".

Preference should be given to the html5 form, so always include this setting in the theme!

#2 Filter (restriction) of search results

In addition to the s query parameter, you can filter the search by post type. To do this, add another input field named post_type to the form:

<input type="hidden" value="post" name="post_type" />

As a result, when we send the form (submit) we will receive a query string of the following form: ?s=text&post_type=post. This means that the search will not be done for all types of posts, but only for the post type specified in the field name="post_type", in this case for the post type post. By default, it says post_type = any (any post type).

You can also filter search results however you like using the pre_get_posts hook.

#3 HTML of the search form through the file `searchform.php`

Create a file searchform.php in the theme folder with the code:

<form role="search" method="get" id="searchform" action="<?php echo home_url( '/' ) ?>" >
	<label class="screen-reader-text" for="s">Search: </label>
	<input type="text" value="<?php echo get_search_query() ?>" name="s" id="s" />
	<input type="submit" id="searchsubmit" value="find" />
</form>

Then, where you want display the search form, call the function get_search_form(), which will display the contents of the file searchform.php we just created:

<?php get_search_form(); ?>

Keep in mind that the search form must send a GET request to the homepage: action="<?php echo home_url( '/' ); ?>", and must have the parameter s (what to search for):

<input type="text" value=""" name="s" id="s" />

#4 HTML search forms with a hook

You can not create the themes searchform.php file, but change the HTML code of the form through the hook get_search_form, which should be inserted into the theme's functions.php file.

add_filter( 'get_search_form', 'my_search_form' );

function my_search_form( $form ) {

	$form = '
	<form role="search" method="get" id="searchform" action="' . home_url( '/' ) . '" >
		<label class="screen-reader-text" for="s">Search query:</label>
		<input type="text" value="' . get_search_query() . '" name="s" id="s" />
		<input type="submit" id="searchsubmit" value="Find" />
	</form>';

	return $form;
}

Changelog

Since 2.7.0	Introduced.
Since 5.2.0	The `$args` array parameter was added in place of an `$echo` boolean flag.

`get_search_form() get search form` code ^{WP 6.7.1}

wp-includes/general-template.php

function get_search_form( $args = array() ) {
	/**
	 * Fires before the search form is retrieved, at the start of get_search_form().
	 *
	 * @since 2.7.0 as 'get_search_form' action.
	 * @since 3.6.0
	 * @since 5.5.0 The `$args` parameter was added.
	 *
	 * @link https://core.trac.wordpress.org/ticket/19321
	 *
	 * @param array $args The array of arguments for building the search form.
	 *                    See get_search_form() for information on accepted arguments.
	 */
	do_action( 'pre_get_search_form', $args );

	$echo = true;

	if ( ! is_array( $args ) ) {
		/*
		 * Back compat: to ensure previous uses of get_search_form() continue to
		 * function as expected, we handle a value for the boolean $echo param removed
		 * in 5.2.0. Then we deal with the $args array and cast its defaults.
		 */
		$echo = (bool) $args;

		// Set an empty array and allow default arguments to take over.
		$args = array();
	}

	// Defaults are to echo and to output no custom label on the form.
	$defaults = array(
		'echo'       => $echo,
		'aria_label' => '',
	);

	$args = wp_parse_args( $args, $defaults );

	/**
	 * Filters the array of arguments used when generating the search form.
	 *
	 * @since 5.2.0
	 *
	 * @param array $args The array of arguments for building the search form.
	 *                    See get_search_form() for information on accepted arguments.
	 */
	$args = apply_filters( 'search_form_args', $args );

	// Ensure that the filtered arguments contain all required default values.
	$args = array_merge( $defaults, $args );

	$format = current_theme_supports( 'html5', 'search-form' ) ? 'html5' : 'xhtml';

	/**
	 * Filters the HTML format of the search form.
	 *
	 * @since 3.6.0
	 * @since 5.5.0 The `$args` parameter was added.
	 *
	 * @param string $format The type of markup to use in the search form.
	 *                       Accepts 'html5', 'xhtml'.
	 * @param array  $args   The array of arguments for building the search form.
	 *                       See get_search_form() for information on accepted arguments.
	 */
	$format = apply_filters( 'search_form_format', $format, $args );

	$search_form_template = locate_template( 'searchform.php' );

	if ( '' !== $search_form_template ) {
		ob_start();
		require $search_form_template;
		$form = ob_get_clean();
	} else {
		// Build a string containing an aria-label to use for the search form.
		if ( $args['aria_label'] ) {
			$aria_label = 'aria-label="' . esc_attr( $args['aria_label'] ) . '" ';
		} else {
			/*
			 * If there's no custom aria-label, we can set a default here. At the
			 * moment it's empty as there's uncertainty about what the default should be.
			 */
			$aria_label = '';
		}

		if ( 'html5' === $format ) {
			$form = '<form role="search" ' . $aria_label . 'method="get" class="search-form" action="' . esc_url( home_url( '/' ) ) . '">
				<label>
					<span class="screen-reader-text">' .
					/* translators: Hidden accessibility text. */
					_x( 'Search for:', 'label' ) .
					'</span>
					<input type="search" class="search-field" placeholder="' . esc_attr_x( 'Search &hellip;', 'placeholder' ) . '" value="' . get_search_query() . '" name="s" />
				</label>
				<input type="submit" class="search-submit" value="' . esc_attr_x( 'Search', 'submit button' ) . '" />
			</form>';
		} else {
			$form = '<form role="search" ' . $aria_label . 'method="get" id="searchform" class="searchform" action="' . esc_url( home_url( '/' ) ) . '">
				<div>
					<label class="screen-reader-text" for="s">' .
					/* translators: Hidden accessibility text. */
					_x( 'Search for:', 'label' ) .
					'</label>
					<input type="text" value="' . get_search_query() . '" name="s" id="s" />
					<input type="submit" id="searchsubmit" value="' . esc_attr_x( 'Search', 'submit button' ) . '" />
				</div>
			</form>';
		}
	}

	/**
	 * Filters the HTML output of the search form.
	 *
	 * @since 2.7.0
	 * @since 5.5.0 The `$args` parameter was added.
	 *
	 * @param string $form The search form HTML output.
	 * @param array  $args The array of arguments for building the search form.
	 *                     See get_search_form() for information on accepted arguments.
	 */
	$result = apply_filters( 'get_search_form', $form, $args );

	if ( null === $result ) {
		$result = $form;
	}

	if ( $args['echo'] ) {
		echo $result;
	} else {
		return $result;
	}
}

get_search_form() │ WP 2.7.0

Hooks from the function

Return

Usage

Examples

#1 Default HTML search forms

#2 Filter (restriction) of search results

#3 HTML of the search form through the file searchform.php

#4 HTML search forms with a hook

Changelog

get_search_form() get search form code WP 6.7.1

Related Functions

Theme files connection

Main Functions

#3 HTML of the search form through the file `searchform.php`

`get_search_form() get search form` code ^{WP 6.7.1}