Title: WordPress Playground for Theme Developers
Published: July 15, 2026
Last modified: July 16, 2026

---

# WordPress Playground for Theme Developers

## In this article

 * [Launching a Playground instance with a theme](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#launching-a-playground-instance-with-a-theme)
    - [Themes in the WordPress themes directory](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#themes-in-the-wordpress-themes-directory)
    - [Themes in a GitHub repository](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#themes-in-a-github-repository)
 * [Setting up a demo theme with Blueprints](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#setting-up-a-demo-theme-with-blueprints)
    - [resetData](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#resetdata)
    - [writeFile](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#writefile)
    - [updateUserMeta](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#updateusermeta)
    - [setSiteOptions](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#setsiteoptions)
    - [plugins](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#plugins)
    - [login](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#login)
 * [Theme development](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#theme-development)
    - [Local theme development and testing with Playground](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#local-theme-development-and-testing-with-playground)
    - [Design your theme using the WordPress UI and save your changes as Pull Requests](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#design-your-theme-using-the-wordpress-ui-and-save-your-changes-as-pull-requests)

[ Back to top](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#wp--skip-link--target)

The WordPress Playground is an innovative tool that allows theme developers to build,
test, and showcase their themes directly in a browser environment.

This guide will show you how to use WordPress Playground to improve your theme development
workflow, create live demos to showcase your theme, and simplify the theme review
process.

Discover how to [Build](https://developer.wordpress.org/playground/about/build),
[Test](https://developer.wordpress.org/playground/about/test), and [Launch](https://developer.wordpress.org/playground/about/launch)
your products with WordPress Playground in the [About Playground](https://developer.wordpress.org/playground/about)
section

## 󠀁[Launching a Playground instance with a theme](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#launching-a-playground-instance-with-a-theme)󠁿

### 󠀁[Themes in the WordPress themes directory](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#themes-in-the-wordpress-themes-directory)󠁿

With WordPress Playground, you can quickly launch a WordPress installation using
any theme available in the [WordPress Themes Directory](https://wordpress.org/themes/).
Simply pass the `theme` [query parameter](https://developer.wordpress.org/playground/developers/apis/query-api)
to the [Playground URL](https://playground.wordpress.net) like this: https://playground.
wordpress.net/?theme=disco.

You can also load any theme from the WordPress themes directory by setting the [`installTheme` step](https://developer.wordpress.org/playground/blueprints/steps#InstallThemeStep)
of a [Blueprint](https://developer.wordpress.org/playground/blueprints/getting-started)
passed to the Playground instance.

    ```language-json
    {
        "steps": [
            {
                "step": "installTheme",
                "themeData": {
                    "resource": "wordpress.org/themes",
                    "slug": "twentytwenty"
                },
                "options": {
                    "activate": true,
                    "importStarterContent": true
                }
            }
        ]
    }
    ```

[Run Blueprint](https://playground.wordpress.net/builder/builder.html#{%22steps%22:[{%22step%22:%22installTheme%22,%22themeData%22:{%22resource%22:%22wordpress.org/themes%22,%22slug%22:%22twentytwenty%22},%22options%22:{%22activate%22:true,%22importStarterContent%22:true}}]})

### 󠀁[Themes in a GitHub repository](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#themes-in-a-github-repository)󠁿

A theme stored in a GitHub repository can also be loaded in a Playground instance
with Blueprints.

With the `themeData` property of the [`installTheme` blueprint step](https://developer.wordpress.org/playground/blueprints/steps#InstallThemeStep),
you can define a [`git:directory` resource](https://developer.wordpress.org/playground/blueprints/steps/resources#gitdirectoryreference)
that will build a theme from the files from a repository in the Playground instance.

Use the [`git:directory` resource](https://developer.wordpress.org/playground/blueprints/steps/resources#gitdirectoryreference)
to load theme source code from a Git repository. It supports branches, tags, commits,
and subdirectories without requiring you to create a ZIP archive first. If your 
theme needs a build step, publish a built ZIP artifact and install that artifact
with a `url` resource instead.

For example the following `blueprint.json` installs a theme from a GitHub repository:

    ```language-json
    {
        "steps": [
            {
                "step": "installTheme",
                "themeData": {
                    "resource": "git:directory",
                    "url": "https://github.com/Automattic/themes",
                    "ref": "trunk",
                    "path": "assembler"
                },
                "options": {
                    "activate": true
                }
            }
        ]
    }
    ```

If your theme is hosted on GitHub, you can automatically add preview buttons to 
your pull requests using the Playground PR Preview GitHub Action. This lets reviewers
test your changes instantly without any setup. See [Adding PR Preview Buttons with GitHub Actions](https://developer.wordpress.org/playground/guides/github-action-pr-preview)
for details.

[Run Blueprint](https://playground.wordpress.net/#{%22steps%22:[{%22step%22:%22installTheme%22,%22themeData%22:{%22resource%22:%22git:directory%22,%22url%22:%22https://github.com/Automattic/themes%22,%22ref%22:%22trunk%22,%22path%22:%22assembler%22},%22options%22:{%22activate%22:true}}],%22$schema%22:%22https://playground.wordpress.net/blueprint-schema.json%22,%22meta%22:{%22title%22:%22Empty%20Blueprint%22,%22author%22:%22https://github.com/akirk/playground-step-library%22}})

A blueprint can be passed to a Playground instance [in several ways](https://developer.wordpress.org/playground/blueprints/using-blueprints).

## 󠀁[Setting up a demo theme with Blueprints](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#setting-up-a-demo-theme-with-blueprints)󠁿

When providing a link to a WordPress Playground instance with a specific theme activated,
you may also want to customize the initial setup for that theme. With Playground’s
[Blueprints](https://developer.wordpress.org/playground/blueprints/getting-started)
you can load, activate, and configure a theme.

Some useful tools and resources provided by the Playground project to work with 
blueprints are:

 * Check the [Blueprints Gallery](https://github.com/WordPress/blueprints/blob/trunk/GALLERY.md)
   to explore real-world code examples of using WordPress Playground to launch a
   WordPress site with a variety of setups.
 * The [WordPress Playground Step Library](https://akirk.github.io/playground-step-library/#)
   tool provides a visual interface to drag or click the steps to create a blueprint
   for WordPress Playground. You can also create your own steps!
 * The [Blueprints builder](https://playground.wordpress.net/builder/builder.html)
   tool allows you edit your blueprint online and run it directly in a Playground
   instance.

Through properties and [`steps`](https://developer.wordpress.org/playground/blueprints/steps)
in the blueprint, you can configure the initial setup of your theme in the Playground
instance.

To provide a good demo of your theme via Playground, you may want to load it with
default content that highlights the features of your theme. Check out the [Providing content for your demo](https://developer.wordpress.org/playground/guides/providing-content-for-your-demo)
guide to learn more about this.

### 󠀁[resetData](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#resetdata)󠁿

With the [`resetData`](https://developer.wordpress.org/playground/blueprints/steps#resetData)
step, you can remove the default content of a WordPress installation in order to
import your own content.

    ```language-json
    "steps": [
        ...,
        {
            "step": "resetData"
        },
        ...
    ]
    ```

[Run Blueprint](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/install-activate-setup-theme-from-gh-repo/blueprint.json)
[See blueprint.json](https://github.com/WordPress/blueprints/blob/eb6da7dfa295a095eea2e424c0ae83a219803a8d/blueprints/install-activate-setup-theme-from-gh-repo/blueprint.json#L16)

### 󠀁[writeFile](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#writefile)󠁿

With the [`writeFile`](https://developer.wordpress.org/playground/blueprints/steps#resetData)
step, you can write data to a file at a specified path. You may want to use this
step to write custom PHP code in a PHP file inside the `mu-plugins` folder of the
Playground WordPress instance, so the code is executed automatically when the WordPress
instance is loaded.
 One of the things you can do through this step is to enable
pretty permalinks for your Playground instance:

    ```language-json
    "steps": [
        ...,
        {
            "step": "writeFile",
            "path": "/wordpress/wp-content/mu-plugins/rewrite.php",
            "data": "<?php /* Use pretty permalinks */ add_action( 'after_setup_theme', function() { global $wp_rewrite; $wp_rewrite->set_permalink_structure('/%postname%/'); $wp_rewrite->flush_rules(); } );"
        },
        ...
    ]
    ```

[Run Blueprint](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/install-activate-setup-theme-from-gh-repo/blueprint.json)
[See blueprint.json](https://github.com/WordPress/blueprints/blob/eb6da7dfa295a095eea2e424c0ae83a219803a8d/blueprints/install-activate-setup-theme-from-gh-repo/blueprint.json#L19)

### 󠀁[updateUserMeta](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#updateusermeta)󠁿

With the [`updateUserMeta`](https://developer.wordpress.org/playground/blueprints/steps#updateUserMeta)
step, you can update any user metadata. For example, you could update the metadata
of the default `admin` user of any WordPress installation:

    ```language-json
    "steps": [
        ...,
        {
            "step": "updateUserMeta",
            "meta": {
                "first_name": "John",
                "last_name": "Doe",
                "admin_color": "modern"
            },
            "userId": 1
        },
        ...
    ]
    ```

[Run Blueprint](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/install-activate-setup-theme-from-gh-repo/blueprint.json)
[See blueprint.json](https://github.com/WordPress/blueprints/blob/eb6da7dfa295a095eea2e424c0ae83a219803a8d/blueprints/install-activate-setup-theme-from-gh-repo/blueprint.json#L24)

### 󠀁[setSiteOptions](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#setsiteoptions)󠁿

With the [`setSiteOptions`](https://developer.wordpress.org/playground/blueprints/steps#setSiteOptions)
step, you can set [site options](https://developer.wordpress.org/apis/options/#available-options-by-category)
such as the site name, description, or page to use for posts.

    ```language-json
    "steps": [
        ...,
        {
            "step": "setSiteOptions",
            "options": {
                "blogname": "Rich Tabor",
                "blogdescription": "Multidisciplinary maker specializing in the intersection of product, design and engineering. Making WordPress.",
                "show_on_front": "page",
                "page_on_front": 6,
                "page_for_posts": 2
            }
        },
        ...
    ]
    ```

[Run Blueprint](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/install-activate-setup-theme-from-gh-repo/blueprint.json)
[See blueprint.json](https://github.com/WordPress/blueprints/blob/eb6da7dfa295a095eea2e424c0ae83a219803a8d/blueprints/install-activate-setup-theme-from-gh-repo/blueprint.json#L50)

There’s also a [`siteOptions`](https://developer.wordpress.org/playground/blueprints/steps/shorthands#siteoptions)
shorthand that can be used instead of the `setSiteOptions` step.

### 󠀁[plugins](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#plugins)󠁿

With the [`plugins`](https://developer.wordpress.org/playground/blueprints/steps/shorthands#plugins)
shorthand you can set a list of plugins you want to be installed and activated with
your theme in the Playground instance.

    ```language-json
    "plugins": ["todo-list-block", "markdown-comment-block"]
    ```

[Run Blueprint](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/install-activate-setup-theme-from-gh-repo/blueprint.json)
[See blueprint.json](https://github.com/WordPress/blueprints/blob/eb6da7dfa295a095eea2e424c0ae83a219803a8d/blueprints/install-activate-setup-theme-from-gh-repo/blueprint.json#L60)

You can also use the [`installPlugin`](https://developer.wordpress.org/playground/blueprints/steps#installPlugin)
step to install and activate plugins for your Playground instance but the shorthand
way is recommended.

### 󠀁[login](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#login)󠁿

With the [`login`](https://developer.wordpress.org/playground/blueprints/steps/shorthands#login)
shorthand you can launch your Playground instance with the admin user logged in.

    ```language-json
     "login": true,
    ```

[Run Blueprint](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/install-activate-setup-theme-from-gh-repo/blueprint.json)
[See blueprint.json](https://github.com/WordPress/blueprints/blob/eb6da7dfa295a095eea2e424c0ae83a219803a8d/blueprints/install-activate-setup-theme-from-gh-repo/blueprint.json#L10)

You can also use the [`login`](https://developer.wordpress.org/playground/blueprints/steps#login)
step to launch your Playground instance logged in with any specific user.

The [“Stylish Press”](https://github.com/WordPress/blueprints/tree/trunk/blueprints/stylish-press)
and [“Loading, activating, and configuring a theme from a GitHub repository”](https://github.com/WordPress/blueprints/tree/trunk/blueprints/install-activate-setup-theme-from-gh-repo)
examples from the [Blueprints Gallery](https://github.com/WordPress/blueprints/blob/trunk/GALLERY.md)
are great references for loading, activating, importing content, and configuring
a block theme on a Playground instance.

## 󠀁[Theme development](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#theme-development)󠁿

### 󠀁[Local theme development and testing with Playground](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#local-theme-development-and-testing-with-playground)󠁿

From the root folder of a block theme’s code, you can quickly load locally a Playground
instance with that theme loaded and activated. You can do that by launching, in 
a theme directory, the [`@wp-playground/cli` command](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli)
from your preferred command line program or the [Visual Code Studio extension](https://developer.wordpress.org/playground/developers/local-development/vscode-extension)
from the [Visual Studio Code](https://code.visualstudio.com/) IDE.

For example:

    ```
    git clone git@github.com:WordPress/community-themes.git
    cd community-themes/blue-note
    npx @wp-playground/cli server --auto-mount
    ```

### 󠀁[Design your theme using the WordPress UI and save your changes as Pull Requests](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#design-your-theme-using-the-wordpress-ui-and-save-your-changes-as-pull-requests)󠁿

You can connect your Playground instance to a GitHub repository and create a Pull
Request with the changes you’ve done through the WordPress UI in the Playground 
instance, leveraging the [Create Block Theme](https://wordpress.org/plugins/create-block-theme/)
plugin. You can also make changes to that theme and export a zip.

Note that you’ll need the [Create Block Theme](https://wordpress.org/plugins/create-block-theme/)
plugin installed and activated in the Playground instance in order to use this workflow.

Check [About Playground > Build > Save changes done on a Block Theme and create GitHub Pull Requests](https://developer.wordpress.org/playground/about/build#save-changes-done-on-a-block-theme-and-create-github-pull-requests)
for more info.

First published

July 15, 2026

Last updated

July 16, 2026

Edit article

[ Improve it on GitHub: WordPress Playground for Theme Developers ](https://raw.githubusercontent.com/WordPress/wordpress-playground/trunk/packages/docs/site/docs/main/guides/for-theme-developers.md)

Changelog

[ See list of changes: WordPress Playground for Theme Developers ](https://developer.wordpress.org/playground/handbook/guides/for-theme-developers/?output_format=md#)

[  Previous: WordPress Playground for Plugin Developers](https://developer.wordpress.org/playground/handbook/guides/for-plugin-developers/)

[  Next: Providing content for your demo with Playground](https://developer.wordpress.org/playground/handbook/guides/providing-content-for-your-demo/)