There is one step to take before writing any CSS to get a WordPress theme working: adding a correctly formatted comment block at the very top of the style.css file. Without reading that block, WordPress does not recognise your theme at all — no matter how correctly the rest of the CSS is written. In this article we look at how this header works, what each field does, what to watch out for when creating a child theme, and the mistakes people make most often.
How Does WordPress Recognise a Theme?
To recognise a theme, WordPress scans every folder under wp-content/themes/ and looks for this comment block at the very top of the style.css file inside it. If the block is not there, or the Theme Name field is empty, WordPress does not see that folder as a valid theme and does not list it on the Appearance > Themes screen. The important point is this: WordPress does not concern itself with the rest of the file's CSS content, it only scans this header. So a style.css containing technically invalid CSS but with a correct header will still be recognised as a theme.
Let's take a concrete example. Suppose you create a style.css file in the folder wp-content/themes/showcase-theme/, but you accidentally put a @charset "UTF-8"; line or an ordinary explanatory CSS comment at the very top of the file. Even if the header block starts right after that line, on the second line of the file, WordPress does not recognise the theme, because the scan starts from the very first line of the file. Moving the same header to the file's actual first line fixes the problem instantly.
style.css Header Fields
| Field | Required? | What it does |
|---|---|---|
| Theme Name | Yes | The only required field for the theme to be recognised; it is the name shown on the Themes screen |
| Theme URI | No | Links to the theme's information page |
| Author | No | Shows the author's name |
| Author URI | No | The link opened when the author's name is clicked |
| Description | No | The description text on the Themes screen |
| Version | No | Shows the version number |
| Requires at least | No | States the minimum WordPress version the theme needs to work |
| Requires PHP | No | States the minimum PHP version the theme needs to work |
| License | No | Shows the licence type |
| License URI | No | Links to the licence text |
| Text Domain | No | The identifier the translation strings are matched against; required for i18n |
| Template | Only in a child theme | States the parent theme's folder name; defines which theme the child theme inherits from |
Requires at least and Requires PHP: Compatibility Checks
The Requires at least and Requires PHP fields let WordPress check the theme's compatibility with the installed version automatically. If the site does not meet those requirements, WordPress marks the theme as incompatible on the Themes screen and prevents activation. This mechanism stops a user on an old PHP version or an un-updated WordPress installation from unknowingly activating the theme and ending up with a broken site.
Child Themes and the Template Line
If you are creating a child theme, you also need to add a Template: line to the header giving the parent theme's folder name. For example, if the parent theme is in the folder wp-content/themes/twentytwentyfour, you add the line Template: twentytwentyfour to the child theme's style.css file. WordPress uses that line to work out which theme to inherit from; while the child theme's own style.css file is used to override the parent's CSS, the PHP template files are also inherited from the parent theme thanks to this same line.
The practical value of the child theme approach comes from this: instead of editing a theme directly, you work in a separate folder built on top of it. Your changes stay in the child theme's own files and the parent theme's files are never touched. Because the Template: line establishes that relationship, every template file, function or style missing from the child is automatically inherited from the parent; you only redefine the parts you want to change inside the child theme.
Text Domain and Translation Matching
Text Domain must be exactly the same as the value used in the theme's load_theme_textdomain() call and in all the __() / _e() translation functions. When those two values do not match, WordPress cannot find the right .mo translation file and the interface always appears in the original text, usually English. This mistake, like other Text Domain mismatches, produces no error message; the translations simply stop working silently.
Common Mistakes
- The header is not at the very top of the file: the block has to be on the genuine first line of the
style.cssfile. If there is a@charsetrule, a blank line or another comment before it, WordPress may not recognise the block and will not list the theme. - Theme Name missing: even if every other field is correct, if
Theme Nameis empty WordPress does not see the folder as a valid theme. - Forgetting the Template line in a child theme: if this line is missing, WordPress treats the child theme as an independent, standalone theme; no template file is inherited from the parent theme and the site usually looks broken.
- A Text Domain mismatch: if the value in the header does not match the slug used in the translation functions, the translations silently fail to work and no error is shown.
Writing the header fields by hand is error-prone, especially in child themes where the Template line has to match the folder name exactly. The tool below helps you produce the required fields in the correct format.