Underscorefunk Design

Design, Illustration, Interaction, and Artistic Direction

Styled Components with PHP/CSS in WordPress

Templates and plugins can have a lot of different output components (partials) which are loaded via get_template_part(). It can sometimes be tricky to keep everything straight and organized. I’ve tried a lot of different approaches and settled on one to keep everything organized and clear. This approach requires you to treat each individual component as a completely stand alone block.Β The beauty of this is that decoupling components creates freedom and clarity for developers! πŸ˜€

In an ideal world the development cycle would look like this:

  1. A client requests that I change the way headings for book summaries are output.
  2. I edit the content (PHP) of the book summary heading.
  3. I edit the appearance (CSS) of the book summary heading.
  4. I commit the change to my version control with:
    ‘Add a line break after the first semi-colon and make the font size smaller’ showing 2 edited files:
    /partials/singular-summary-book/heading.phpΒ  ← content
    /ui/components/singular-summary-book/_heading.scss ← appearance

It’s easy to see what the change was, where it happened, and reverting to previous versions doesn’t really impact anything else on the site. That sounds pretty stress free to me.Β Again, we’re aiming for transparency, clarity, and consistency here. I might change ‘components’ to ‘partials’ in the UI folder to be even more consistent. There’s always room for improvement πŸ™‚

Component Output File Structure (PHP)


Each individual output block should be a component and separate file, stored in its parent component, within the partials directory of a theme or plugin.

At this point it’s important to make a few distinctions regarding the naming conventions I employ.

  • singular denotes that a post/post-type object is being viewed as a complete and whole object. (e.g. You’re reading the whole article/post/whatever). It is the focus of the reader/user.
  • singular-summary denotes that a post/post-type object is being summarized and not presented in its entirety. (e.g. You’re reading a teaser which links to the full article).

These components can then be suffixed with their post-type name to create things like singular-movie, or singular-summary-movie, or singular-summary-book.

This yields a structure that is very clear, organized, and allows developers to easily extend components or override them by adding additional files.

We can imagine that singular.php would contain something like this.

… some output here …

ing for this component is now a cake walk.


WordPress sets a series of classes in theΒ <body> tag which can be filtered by the body_class filter. For single post/post-type pages it adds ‘single’ and ‘single-{post-type}’. We’re using ‘singular’ and ‘singular-{post-type}’ to avoid that conflict. Just be aware that when creating partials you’ll need to watch out for conflicts like that, or your styling might cascade in ways that you don’t expect.

Coming soon

  • How I employ this approach to loading archives and other partial types.
  • How I populate the content of these components/partials in a later post.
  • How I create overrides that cascade.

Component Style File Structure (CSS)


Each component has a matching style file that only styles itself.Β In this example I’m using SCSS files which are processed and joined into one big (but minified) CSS file. This 1:1 relationship is really important and will help you keep the source code organized. I’ve decided to call the folder ‘ui’ instead of ‘styles’ because styles are now closely coupled to user interaction (javascript). With this structure it’s easy to keep everything (css and js) in the same place. Note _heading.js which handles the user interaction for _heading.css.

We can imagine that singular.scss would contain something like this.

In this example I have the presentation of ‘.singular’ changing because of the context ‘.threatre-view’ (a parent object with that class, possibly even in the body tag). For example, let’s say that someone clicks on the ‘theatre view’ button which adds the ‘theatre-view’ class to <body>. As a result we might want to compress the way singular items are being displayed.

One school of thought would argue that all ‘theatre-view’ modifications should exist in a ‘theatre-view’ css file. The problem I have with that is you’ve now separated context from target. In my mind, those two have strong coupling and should live together.

I’ve grown to appreciate what I’ll call a styled-component approach. In the react world, the styles would live with the output. We can’t quite get there with PHP, but this is pretty close


Output components

It’s important to have common language, naming conventions, and a consistent structure for your code. Flexibility is great in a lot of ways but loosely coupled names/meanings can create confusion, sloppy code, or the dreaded mental overhead of trying to pick the perfect name for something.

For this reason I like to force the following rules for naming/organizing files that generate output.

Templates: A file that composes output top to bottom, from outputting file headers to the end of the request response. Loaded through the template_include filter.

Partials: A chunk of output that is not a complete template. Output through the get_template_part() function.

While partials are a template of sorts, I like to make this distinction for the sake of clarity. It’s also encouraged by some of WordPress’ naming conventions. In my mind, the idea of loading a file fromΒ /partialsΒ throughΒ get_template_part()Β makes a lot of sense. I’m loading a part and it’s in ‘partials’.Β On the higher order side of things, loading a file fromΒ /templatesΒ through theΒ template_includeΒ filter makes a lot of sense too.

I really wish WordPress would have enforced some structure like this from the get go instead of tossing everything into the theme root folder. I’ll expand on some solutions to force WordPress to be a bit more organized later on, as well as going into detail about how I organize my partials.