get_search_form( array $args = array() )
Display search form.
Contents
Description Description
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.
Parameters Parameters
- $args
-
(array) (Optional) Array of display arguments.
- 'echo'
(bool) 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 value: array()
- 'echo'
Return Return
(string|void) String when the $echo param is false.
Source Source
File: 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 * * @link https://core.trac.wordpress.org/ticket/19321 */ do_action( 'pre_get_search_form' ); $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. */ $args = apply_filters( 'search_form_args', $args ); $format = current_theme_supports( 'html5', 'search-form' ) ? 'html5' : 'xhtml'; /** * Filters the HTML format of the search form. * * @since 3.6.0 * * @param string $format The type of markup to use in the search form. * Accepts 'html5', 'xhtml'. */ $format = apply_filters( 'search_form_format', $format ); $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 ( isset( $args['aria_label'] ) && $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">' . _x( 'Search for:', 'label' ) . '</span> <input type="search" class="search-field" placeholder="' . esc_attr_x( 'Search …', '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">' . _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 * * @param string $form The search form HTML output. */ $result = apply_filters( 'get_search_form', $form ); if ( null === $result ) { $result = $form; } if ( isset( $args['echo'] ) && $args['echo'] ) { echo $result; } else { return $result; } }
Expand full source code Collapse full source code View on Trac
Changelog Changelog
Version | Description |
---|---|
5.2.0 | The $args array parameter was added in place of an $echo boolean flag. |
2.7.0 | Introduced. |
More Information More Information
Usage Usage
get_search_form( $echo );
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
Theme Form
If you do have
searchform.php
in your theme, it will be used instead. Keep in mind that the search form should do a GET to the homepage of your blog. The input text field should be nameds
and you should always include a label like in the examples above.Example of a custom
searchform.php
:The only parameter here that will be submitted is s with the value of the current search query. However, you can refine it in many ways. For example by only showing posts in the search results. This can be done with the next addition to the form above:
Here we submit the value post. The default value is any, meaning, posts, pages and custom post types. With the input above added to the form it will now only search in posts with the
post_type
post. There are many additions like this. With avar_dump
of the object$wp_query
you can see all the default values of the search variables. With avar_dump
of$wp_query->query
you can see the current query.A last option is to write a custom function (in your
functions.php
file) and hook that function to theget_search_form
action hook.Expand full source codeCollapse full source code
Default HTML5 Form
Since WordPress 3.6, If your theme supports HTML5 Markup, which happens if it uses:
WordPress will render its built-in HTML5 search form:
Among the changes is that the form has a
class="search-form"
. Also, the input istype="search"
and nottype="text"
. Furthermore there is a placeholder, which displays text when appropriate, which means you don’t need JavaScript to display the placeholder. There are no elements with an id anymore, so you can have multiple searchforms in a valid document.Default HTML4 Form
If you don’t have
searchform.php
in your theme, WordPress will render its built-in search form:The above form is used on HTML4 websites.
This is incorrect as it overrides the native semantics of the element.
Place
role="search"
before or after the <form elementor