WordPress.org
Get WordPress
WordPress.org

WordPress Developer Resources

user_search_columns

apply_filters( ‘user_search_columns’, string[] $search_columns, string $search, WP_User_Query $query )

In this article

Back to top

Filters the columns to search in a WP_User_Query search.

Description

The default columns depend on the search term, and include ‘ID’, ‘user_login’, ‘user_email’, ‘user_url’, ‘user_nicename’, and ‘display_name’.

Parameters

$search_columnsstring[]
Array of column names to be searched.
$searchstring
Text being searched.
$queryWP_User_Query
The current WP_User_Query instance.

More Information

The user_search_columns filter is used to determine which user fields in the database are used when performing a search on user information.

When the ‘user_search_columns’ filter is called, it is passed three parameters: an array of fields to search, the search term, WP_User_Query object

<pre>add_filter( 'user_search_columns', 'filter_function_name', 10, 3 );

function filter_function_name( $search_columns, $search, $wp_user_query ) {
// Alter $search_columns to include the fields you want to search on
return $search_columns;
}

Where ‘filter_function_name’ is the function WordPress should call when the filter is run. Note that the filter function must return a value after it is finished processing or the search terms will be empty.

filter_function_name should be unique function name. It cannot match any other function name already declared

Source

$search_columns = apply_filters( 'user_search_columns', $search_columns, $search, $this );

View all references View on Trac View on GitHub

Used byDescription
WP_User_Query::prepare_query()wp-includes/class-wp-user-query.php

Prepares the query variables.

Changelog

VersionDescription
3.6.0Introduced.

User Contributed Notes

  1. Skip to note 5 content
    Collins Mbaka
    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

    Add a field to search on

    In this example, the user’s URL is also added to the list of columns searched

    add_filter( 'user_search_columns', 'wpdocs_filter_function_name', 10, 3 );
    
function wpdocs_filter_function_name( $search_columns, $search, $wp_user_query ) {
    $search_columns[] = 'user_url';
    return $search_columns;
}
  2. Skip to note 6 content
    Collins Mbaka
    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

    Alter search fields based on the search term

    In this example, if the user searches for something with ‘.com’ in it only the user_url field will be searched

    add_filter( 'user_search_columns', 'wpdocs_filter_function_name', 10, 2 );

function wpdocs_filter_function_name( $search_columns, $search ) {
    $val = strpos( $search, '.com' );
    
    if ( false !== $val ) {
	    $search_columns = array( 'user_url' );
    }
    
    return $search_columns;
}
  3. Skip to note 7 content
    Akira Tachibana
    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

    (From Codex)
    Add a field to search on
    In this example the user’s URL is also added to the list of columns searched

    add_filter( 'user_search_columns', 'filter_function_name', 10, 3 );
    
function filter_function_name( $search_columns, $search, $wp_user_query ) {
    $search_columns[] = 'user_url';
    return $search_columns;
}
  4. Skip to note 8 content
    Akira Tachibana
    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

    (From Codex)
    Alter search fields based on search term

    In this example if the user searches for something with ‘.com’ in it only the user_url field will be searched.

    add_filter( 'user_search_columns', 'filter_function_name', 10, 3 );

function filter_function_name( $search_columns, $search, $wp_user_query ) {
    $val = strpos($search, '.com');
    
    if( $val !== false ) {
	    $search_columns = array('user_url');
    }
    
    return $search_columns;
}

You must log in before being able to contribute a note or feedback.