apply_filters( "pre_option_{$option}", mixed $pre_option, string $option, mixed $default )

Filters the value of an existing option before it is retrieved.

Description Description

The dynamic portion of the hook name, $option, refers to the option name.

Returning a truthy value from the filter will effectively short-circuit retrieval and return the passed value instead.

Top ↑

Parameters Parameters


(mixed) The value to return instead of the option value. This differs from $default, which is used as the fallback value in the event the option doesn't exist elsewhere in get_option(). Default false (to skip past the short-circuit).


(string) Option name.


(mixed) The fallback value to return if the option does not exist. Default false.

Top ↑

More Information More Information

  • This hook is used to temporarily alter a WordPress option before the display of a specific view. WordPress options (e.g. the blog configuration) are usually set in the back-end by the user or programmatically by a plugin. The options are stored in the database. To alter the value of an option during the rendering of a page without changing it permanently in the database, you may use this hook.
  • Example option name {$option} can the following:

  • For a list of all available options, call
    which returns the list of available options as an array that you could store in a variable or display for debugging purposes.

Top ↑

Source Source

File: wp-includes/option.php

View on Trac

Top ↑

Changelog Changelog

Version Description
4.9.0 The $default parameter was added.
4.4.0 The $option parameter was added.
1.5.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Drew Jaynes

    Example: Filter the blogname option on the homepage

     * Filters the blogname option on the homepage.
     * @param false|mixed $value   Pre-option value. Default false.
     * @param string      $option  Option name.
     * @param mixed       $default Default option value.
     * @return false|mixed (Maybe) filtered pre-option value.
    function wp_docs_pre_filter_option( $pre_option, $option, $default ) {
        if ( is_home() ) {
            $pre_option = 'My Awesome Homepage';
        return $pre_option;
    add_filter( 'pre_option_blogname', 'wp_docs_pre_filter_option', 10, 3 );
  2. Skip to note 2 content
    Contributed by stevenlinx

    Example migrated from Codex:

    The example below shows how to alter the amount of displayed posts per page for a specific category (here, the ‘foo’ category). The code is added to the functions.php file of the theme.

    add_filter('pre_option_posts_per_page', 'limit_posts_per_page');
    function limit_posts_per_page( $posts_per_page ) {
       global $wp_query;
       if ( $wp_query->query_vars['category_name'] == 'foo' )
          return 20;
       return $posts_per_page;

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