Title: Custom_Background::wp_set_background_image
Published: April 25, 2014
Last modified: February 24, 2026

---

# Custom_Background::wp_set_background_image()

## In this article

 * [Source](https://developer.wordpress.org/reference/classes/custom_background/wp_set_background_image/?output_format=md#source)
 * [Hooks](https://developer.wordpress.org/reference/classes/custom_background/wp_set_background_image/?output_format=md#hooks)
 * [Related](https://developer.wordpress.org/reference/classes/custom_background/wp_set_background_image/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/classes/custom_background/wp_set_background_image/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/classes/custom_background/wp_set_background_image/?output_format=md#wp--skip-link--target)

This method has been deprecated since 3.5.0.

## 󠀁[Source](https://developer.wordpress.org/reference/classes/custom_background/wp_set_background_image/?output_format=md#source)󠁿

    ```php
    public function wp_set_background_image() {
    	check_ajax_referer( 'custom-background' );

    	if ( ! current_user_can( 'edit_theme_options' ) || ! isset( $_POST['attachment_id'] ) ) {
    		exit;
    	}

    	$attachment_id = absint( $_POST['attachment_id'] );

    	$sizes = array_keys(
    		/** This filter is documented in wp-admin/includes/media.php */
    		apply_filters(
    			'image_size_names_choose',
    			array(
    				'thumbnail' => __( 'Thumbnail' ),
    				'medium'    => __( 'Medium' ),
    				'large'     => __( 'Large' ),
    				'full'      => __( 'Full Size' ),
    			)
    		)
    	);

    	$size = 'thumbnail';
    	if ( in_array( $_POST['size'], $sizes, true ) ) {
    		$size = esc_attr( $_POST['size'] );
    	}

    	update_post_meta( $attachment_id, '_wp_attachment_is_custom_background', get_option( 'stylesheet' ) );

    	$url       = wp_get_attachment_image_src( $attachment_id, $size );
    	$thumbnail = wp_get_attachment_image_src( $attachment_id, 'thumbnail' );
    	set_theme_mod( 'background_image', sanitize_url( $url[0] ) );
    	set_theme_mod( 'background_image_thumb', sanitize_url( $thumbnail[0] ) );
    	exit;
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-admin/includes/class-custom-background.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-admin/includes/class-custom-background.php#L616)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-admin/includes/class-custom-background.php#L616-L650)

## 󠀁[Hooks](https://developer.wordpress.org/reference/classes/custom_background/wp_set_background_image/?output_format=md#hooks)󠁿

 [apply_filters( ‘image_size_names_choose’, string[] $size_names )](https://developer.wordpress.org/reference/hooks/image_size_names_choose/)

Filters the names and labels of the default image sizes.

## 󠀁[Related](https://developer.wordpress.org/reference/classes/custom_background/wp_set_background_image/?output_format=md#related)󠁿

| Uses | Description | 
| [set_theme_mod()](https://developer.wordpress.org/reference/functions/set_theme_mod/)`wp-includes/theme.php` |

Updates theme modification value for the active theme.

  | 
| [wp_get_attachment_image_src()](https://developer.wordpress.org/reference/functions/wp_get_attachment_image_src/)`wp-includes/media.php` |

Retrieves an image to represent an attachment.

  | 
| [update_post_meta()](https://developer.wordpress.org/reference/functions/update_post_meta/)`wp-includes/post.php` |

Updates a post meta field based on the given post ID.

  | 
| [current_user_can()](https://developer.wordpress.org/reference/functions/current_user_can/)`wp-includes/capabilities.php` |

Returns whether the current user has the specified capability.

  | 
| [__()](https://developer.wordpress.org/reference/functions/__/)`wp-includes/l10n.php` |

Retrieves the translation of $text.

  | 
| [esc_attr()](https://developer.wordpress.org/reference/functions/esc_attr/)`wp-includes/formatting.php` |

Escaping for HTML attributes.

  | 
| [check_ajax_referer()](https://developer.wordpress.org/reference/functions/check_ajax_referer/)`wp-includes/pluggable.php` |

Verifies the Ajax request to prevent processing requests external of the blog.

  | 
| [sanitize_url()](https://developer.wordpress.org/reference/functions/sanitize_url/)`wp-includes/formatting.php` |

Sanitizes a URL for database or redirect usage.

  | 
| [absint()](https://developer.wordpress.org/reference/functions/absint/)`wp-includes/load.php` |

Converts a value to non-negative integer.

  | 
| [apply_filters()](https://developer.wordpress.org/reference/functions/apply_filters/)`wp-includes/plugin.php` |

Calls the callback functions that have been added to a filter hook.

  | 
| [get_option()](https://developer.wordpress.org/reference/functions/get_option/)`wp-includes/option.php` |

Retrieves an option value based on an option name.

  |

[Show 8 more](https://developer.wordpress.org/reference/classes/custom_background/wp_set_background_image/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/classes/custom_background/wp_set_background_image/?output_format=md#)

## 󠀁[Changelog](https://developer.wordpress.org/reference/classes/custom_background/wp_set_background_image/?output_format=md#changelog)󠁿

| Version | Description | 
| [3.5.0](https://developer.wordpress.org/reference/since/3.5.0/) | Deprecated.  | 
| [3.4.0](https://developer.wordpress.org/reference/since/3.4.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Fclasses%2Fcustom_background%2Fwp_set_background_image%2F)
before being able to contribute a note or feedback.