BugWP logo BugWP
Back to Community
Home / Community / Core → Developing with wordpress

Troubleshooting Block Theme CSS: Why Your Styles Aren't Showing Up

15 threads Sep 7, 2025 Core → Developing with wordpress

Content

If you're developing a block theme and finding that your carefully crafted CSS isn't appearing where you expect it—whether on the front-end, in the editor, or for specific blocks—you're not alone. This is a common challenge when working with WordPress's full-site editing (FSE) and the theme.json system. Let's break down why this happens and explore the most effective solutions.

Common Scenarios and Their Solutions

1. Front-End Styles Not Loading

As seen in Thread 1, a user tried to enqueue a CSS file for the search block using wp_enqueue_block_style() in functions.php, but it didn't apply on the front-end. This often happens because the function must be called within the correct hook. The 'theme_setup' function needs to be hooked properly.

Solution: Ensure your function is attached to the after_setup_theme hook.

function theme_setup() {
    // Your wp_enqueue_block_style code here
}
add_action( 'after_setup_theme', 'theme_setup' );

2. theme.json CSS Variables Not Reflecting in the Editor

In Thread 2, a user defined custom spacing sizes using CSS variables in theme.json, but they only worked on the front-end, not in the editor. The editor and front-end are two different contexts, and the editor may not automatically load the same CSS file where your :root variables are defined.

Solution: Make sure the CSS file containing your variable declarations (e.g., style.css) is enqueued for both the front-end and the editor. You can use add_editor_style() to ensure it loads in the editing interface.

add_editor_style( 'style.css' );

3. Block Layout CSS Missing on Front-End

Thread 3 highlights an issue where dynamic layout classes (like .wp-container-core-group-is-layout-3) generated by the editor are not output on the front-end. This is typically not a missing enqueue issue but a fundamental characteristic of how the block editor works. The editor generates inline styles for layout previews, but the front-end relies on the theme's CSS and theme.json configuration to render the final layout.

Solution: Do not rely on the editor's auto-generated container classes for front-end styling. Instead, define your layout styles for blocks (like Group, Columns) directly in your theme's CSS or by configuring the layout settings in your theme.json file.

4. theme.json Settings Seem Ignored

Several threads (5, 6, 7, 11) show users configuring settings in theme.json (for blockGap, margins, padding) that don't take effect. A common reason is incorrect JSON structure or placement. For example, block-specific styles belong under the top-level "styles" key, not under "settings".

Solution: Double-check the structure of your theme.json file against the official schema. For instance, to style a core/group block's gap, the correct placement is:

{
  "styles": {
    "blocks": {
      "core/group": {
        "spacing": {
          "blockGap": "0.625rem"
        }
      }
    }
  }
}

Also, ensure you are not modifying the core wp-includes/theme.json file, as mentioned in Thread 11. All customizations must be in your own theme's theme.json.

5. Using theme.json for Custom CSS

For one-off CSS overrides that are not covered by theme.json settings, you can use the "css" property under "styles", as a user discovered in Thread 8 to modify the page list indent.

{
  "styles": {
    "css": ".wp-block-page-list ul { padding-left: 10px; }"
  }
}

General Best Practices and Checks

  • Cache: Always clear any caching plugins or server-level cache after making changes to theme.json or CSS files.
  • Specificity: If your CSS is loaded but being overridden, use more specific selectors. WordPress adds a lot of default styles.
  • Build Tools: If you're using a build process like Webpack (Thread 9), ensure it's configured correctly to process and output your CSS files to the right location.
  • Child Theme: Always make these changes in a child theme if you are customizing a third-party theme. This prevents your work from being lost during updates.

By understanding the separation between editor and front-end styles, using the correct hooks, and validating your theme.json structure, you can resolve most issues of CSS not appearing in your block theme.

Related Support Threads Support