Skip to content

General: Add opt-in <search> element support to the core search form #11913

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
adamsilverstein wants to merge 10 commits into
base: trunk
Choose a base branch
from
Open

General: Add opt-in <search> element support to the core search form #11913

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
540ac7a
General: Add opt-in `<search>` element support to the core search form.
adamsilverstein May 21, 2026
e0f3917
Bundled Themes: Honor the `wrap_in_search` argument in classic search…
adamsilverstein May 21, 2026
c92a528
Add void return types to test methods
westonruter May 27, 2026
74ce202
Declare type of $args variable in template
westonruter May 27, 2026
6b3329f
Fix typing for get_search_form() with param and conditional return ty…
westonruter May 27, 2026
3028590
Declare array type for args
westonruter May 27, 2026
c2eb96d
Make args non-optional
westonruter May 27, 2026
c71d2d2
General: Deduplicate html5 search form markup.
adamsilverstein May 27, 2026
e81153f
Update src/wp-includes/general-template.php
adamsilverstein May 28, 2026
cb20e40
General: Remove stray space in <search> opening tag.
adamsilverstein Jun 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion src/wp-content/themes/twentyseventeen/searchform.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,17 @@
* @version 1.0
*/

/** @var array{ wrap_in_search: bool, aria_label: string } $args */

?>

<?php $unique_id = esc_attr( twentyseventeen_unique_id( 'search-form-' ) ); ?>

<form role="search" method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
<?php $twentyseventeen_wrap_in_search = ! empty( $args['wrap_in_search'] ); ?>
<?php if ( $twentyseventeen_wrap_in_search ) : ?>
<search>
<?php endif; ?>
<form <?php echo $twentyseventeen_wrap_in_search ? '' : 'role="search" '; ?>method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
<label for="<?php echo $unique_id; ?>">
<span class="screen-reader-text">
<?php
Expand All @@ -29,3 +35,6 @@
?>
</span></button>
</form>
<?php if ( $twentyseventeen_wrap_in_search ) : ?>
</search>
<?php endif; ?>
11 changes: 10 additions & 1 deletion src/wp-content/themes/twentysixteen/searchform.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,15 @@
* @since Twenty Sixteen 1.0
*/

/** @var array{ wrap_in_search: bool, aria_label: string } $args */

?>

<form role="search" method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
<?php $twentysixteen_wrap_in_search = ! empty( $args['wrap_in_search'] ); ?>
<?php if ( $twentysixteen_wrap_in_search ) : ?>
<search>
<?php endif; ?>
<form <?php echo $twentysixteen_wrap_in_search ? '' : 'role="search" '; ?>method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
<label>
<span class="screen-reader-text">
<?php
Expand All @@ -26,3 +32,6 @@
?>
</span></button>
</form>
<?php if ( $twentysixteen_wrap_in_search ) : ?>
</search>
<?php endif; ?>
12 changes: 11 additions & 1 deletion src/wp-content/themes/twentytwenty/searchform.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@
* @since Twenty Twenty 1.0
*/

/** @var array{ wrap_in_search: bool, aria_label: string } $args */

/*
* Generate a unique ID for each form and a string containing an aria-label
* if one was passed to get_search_form() in the args array.
Expand All @@ -22,8 +24,13 @@
if ( empty( $twentytwenty_aria_label ) && ! empty( $args['label'] ) ) {
$twentytwenty_aria_label = 'aria-label="' . esc_attr( $args['label'] ) . '"';
}

$twentytwenty_wrap_in_search = ! empty( $args['wrap_in_search'] );
?>
<form role="search" <?php echo $twentytwenty_aria_label; ?> method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
<?php if ( $twentytwenty_wrap_in_search ) : ?>
<search<?php echo $twentytwenty_aria_label ? ' ' . $twentytwenty_aria_label : ''; ?>>
<?php endif; ?>
<form <?php echo $twentytwenty_wrap_in_search ? '' : 'role="search" ' . $twentytwenty_aria_label . ' '; ?>method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
<label for="<?php echo esc_attr( $twentytwenty_unique_id ); ?>">
<span class="screen-reader-text">
<?php
Expand All @@ -35,3 +42,6 @@
</label>
<input type="submit" class="search-submit" value="<?php echo esc_attr_x( 'Search', 'submit button', 'twentytwenty' ); ?>" />
</form>
<?php if ( $twentytwenty_wrap_in_search ) : ?>
</search>
<?php endif; ?>
12 changes: 11 additions & 1 deletion src/wp-content/themes/twentytwentyone/searchform.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,16 +12,26 @@
* @since Twenty Twenty-One 1.0
*/

/** @var array{ wrap_in_search: bool, aria_label: string } $args */

/*
* Generate a unique ID for each form and a string containing an aria-label
* if one was passed to get_search_form() in the args array.
*/
$twentytwentyone_unique_id = wp_unique_id( 'search-form-' );

$twentytwentyone_aria_label = ! empty( $args['aria_label'] ) ? 'aria-label="' . esc_attr( $args['aria_label'] ) . '"' : '';

$twentytwentyone_wrap_in_search = ! empty( $args['wrap_in_search'] );
?>
<form role="search" <?php echo $twentytwentyone_aria_label; ?> method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
<?php if ( $twentytwentyone_wrap_in_search ) : ?>
<search<?php echo $twentytwentyone_aria_label ? ' ' . $twentytwentyone_aria_label : ''; ?>>
<?php endif; ?>
<form <?php echo $twentytwentyone_wrap_in_search ? '' : 'role="search" ' . $twentytwentyone_aria_label . ' '; ?>method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
<label for="<?php echo esc_attr( $twentytwentyone_unique_id ); ?>"><?php _e( 'Search&hellip;', 'twentytwentyone' ); // phpcs:ignore: WordPress.Security.EscapeOutput.UnsafePrintingFunction -- core trusts translations ?></label>
<input type="search" id="<?php echo esc_attr( $twentytwentyone_unique_id ); ?>" class="search-field" value="<?php echo get_search_query(); ?>" name="s" />
<input type="submit" class="search-submit" value="<?php echo esc_attr_x( 'Search', 'submit button', 'twentytwentyone' ); ?>" />
</form>
<?php if ( $twentytwentyone_wrap_in_search ) : ?>
</search>
<?php endif; ?>
44 changes: 34 additions & 10 deletions src/wp-includes/general-template.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -227,18 +227,28 @@ function get_template_part( $slug, $name = null, $args = array() ) {
*
* @since 2.7.0
* @since 5.2.0 The `$args` array parameter was added in place of an `$echo` boolean flag.
* @since 7.1.0 Added the `$wrap_in_search` argument and the `search-element` theme support
* feature to wrap the form in a `<search>` element.
*
* @param array $args {
* Optional. Array of display arguments.
*
* @type bool $echo Whether to echo or return the form. Default true.
* @type string $aria_label ARIA label for the search form. Useful to distinguish
* multiple search forms on the same page and improve
* accessibility. Default empty.
* @type bool $echo Whether to echo or return the form. Default true.
* @type string $aria_label ARIA label for the search form. Useful to distinguish
* multiple search forms on the same page and improve
* accessibility. Default empty.
* @type bool $wrap_in_search Whether to wrap the form in a semantic HTML `<search>`
* landmark element and drop the now-redundant `role="search"`
* attribute on the form. Only applies to the 'html5' format.
* Defaults to true when the theme declares support for the
* 'search-element' feature, false otherwise.
* }
* @return void|string Void if 'echo' argument is true, search form HTML if 'echo' is false.
* @return null|string Null if 'echo' argument is true, search form HTML if 'echo' is false.
*
* @phpstan-param array{ echo?: bool, aria_label?: string, wrap_in_search?: bool } $args
* @phpstan-return ( $args is array{ echo: false } ? string : null )
*/
function get_search_form( $args = array() ) {
function get_search_form( $args = array() ): ?string {
/**
* Fires before the search form is retrieved, at the start of get_search_form().
*
Expand Down Expand Up @@ -269,8 +279,9 @@ function get_search_form( $args = array() ) {

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

$args = wp_parse_args( $args, $defaults );
Expand Down Expand Up @@ -322,7 +333,7 @@ function get_search_form( $args = array() ) {
}

if ( 'html5' === $format ) {
$form = '<form role="search" ' . $aria_label . 'method="get" class="search-form" action="' . esc_url( home_url( '/' ) ) . '">
$form_inner = '
<label>
<span class="screen-reader-text">' .
/* translators: Hidden accessibility text. */
Expand All @@ -331,7 +342,19 @@ function get_search_form( $args = array() ) {
<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>';
';

if ( $args['wrap_in_search'] ) {
/*
* Wrap the form in a <search> landmark element. The implicit ARIA role
* of <search> provides the search landmark, so role="search" is omitted
* from the form to avoid nesting two identical landmarks. Any aria-label
* names the <search> landmark instead of the form.
*/
$form = '<search' . ( $aria_label ? ' ' . trim( $aria_label ) : '' ) . '><form method="get" class="search-form" action="' . esc_url( home_url( '/' ) ) . '">' . $form_inner . '</form></search>';
} else {
$form = '<form role="search" ' . $aria_label . 'method="get" class="search-form" action="' . esc_url( home_url( '/' ) ) . '">' . $form_inner . '</form>';
}
} else {
$form = '<form role="search" ' . $aria_label . 'method="get" id="searchform" class="searchform" action="' . esc_url( home_url( '/' ) ) . '">
<div>
Expand Down Expand Up @@ -364,6 +387,7 @@ function get_search_form( $args = array() ) {

if ( $args['echo'] ) {
echo $result;
return null;
} else {
return $result;
}
Expand Down
3 changes: 3 additions & 0 deletions src/wp-includes/theme.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2647,6 +2647,8 @@ function get_theme_starter_content() {
* see `WP_Theme_JSON::APPEARANCE_TOOLS_OPT_INS` for a complete list.
* @since 6.6.0 The `editor-spacing-sizes` feature was added.
* @since 7.0.0 The `html5` feature's 'script' and 'style' arguments are deprecated and unused.
* @since 7.1.0 The `search-element` feature wraps the core search form markup in the
* HTML `<search>` landmark element.
*
* @global array $_wp_theme_features
*
Expand Down Expand Up @@ -2683,6 +2685,7 @@ function get_theme_starter_content() {
* - 'post-formats'
* - 'post-thumbnails'
* - 'responsive-embeds'
* - 'search-element'

@westonruter westonruter May 28, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Question: Since SEARCH is part of HTML5, would it not make sense as a sub-feature under html5?

@adamsilverstein adamsilverstein May 31, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, good idea! will do.

* - 'starter-content'
* - 'title-tag'
* - 'widgets'
Expand Down
Loading
Loading