The exact syntax WordPress parses
The header must be a standard CSS comment, starting with /* and ending with */, placed as the very first thing in style.css before any actual CSS rules. Each field is a line in the format "Field Name: value". WordPress uses PHP's get_file_data() function to read these lines with regular expressions, so field names must match exactly, including capitalization conventions, or the value will not be picked up.
Required and recommended fields
Only Theme Name is technically required for the theme to appear in Appearance → Themes with a usable label; without it, WordPress may still install the theme but list it with an empty or fallback name. The other fields below are strongly recommended because they populate the theme details screen and matter if you ever submit the theme to WordPress.org.
- Theme Name: My Theme — required, shown in the admin
- Theme URI: https://example.com/my-theme — link to theme homepage
- Author: Jane Doe — displayed on the theme details popup
- Author URI: https://example.com — link to author site
- Description: A short summary of the theme.
- Version: 1.0.0 — used for cache-busting and update checks
- Requires at least: 6.0 — minimum WordPress version
- Requires PHP: 7.4 — minimum PHP version
- License: GPL v2 or later
- License URI: https://www.gnu.org/licenses/gpl-2.0.html
- Text Domain: my-theme — must match the folder/slug for translations
- Tags: blog, one-column, custom-menu — used for WordPress.org filtering only
A complete, correctly formatted example
Here is the full block as it should appear at the top of style.css, with nothing before it, not even a blank line, since WordPress reads a fixed number of bytes from the start of the file:
- /*
- Theme Name: My Theme
- Theme URI: https://example.com/my-theme
- Author: Jane Doe
- Author URI: https://example.com
- Description: A clean, fast theme converted from a live site.
- Version: 1.0.0
- Requires at least: 6.0
- Requires PHP: 7.4
- License: GPL v2 or later
- License URI: https://www.gnu.org/licenses/gpl-2.0.html
- Text Domain: my-theme
- */
Why Text Domain has to match the folder name
Text Domain is used by WordPress's translation functions like __() and _e() to look up the correct .mo language file for the theme. If it does not match the theme's folder slug, translations silently fail to load even when the files are present in the languages folder, which is a subtle bug that has nothing to do with the translation files themselves.
This field does not affect whether the theme installs or activates; it only affects internationalization, so a mismatch will not throw any visible error, making it easy to overlook during testing.
Common header mistakes that cause silent problems
The most frequent mistake is placing something before the opening /* comment, such as a UTF-8 byte order mark or a blank line, which can prevent WordPress from finding the header at all since it only scans the first 8KB of the file. Another common issue is using smart quotes or curly apostrophes copied from a word processor instead of plain ASCII characters, which breaks the field parsing.
A third mistake is duplicating Version numbers between style.css and any versioned assets, which is not a WordPress requirement but does affect whether wp_enqueue_style calls bust the browser cache correctly after updates.
Validating your header before distributing the theme
Install the theme on a local WordPress instance and open Appearance → Themes; hover over the theme card and click Theme Details to confirm every field renders as expected. The Theme Check plugin will also flag missing or malformed header fields automatically, which is faster than checking by eye across multiple themes.
Frequently asked questions
- Is Text Domain required for a WordPress theme to activate?
- No, a theme will activate fine without it, but translations will not work correctly unless Text Domain matches the theme's folder slug exactly.
- Can I put comments or extra CSS before the theme header in style.css?
- No, the header comment block must be the very first content in the file with nothing before it, since WordPress only scans a limited number of bytes from the start of the file.
- What happens if I omit Theme Name entirely?
- The theme may still install, but it will typically show up in Appearance → Themes with a blank or fallback name derived from the folder, which looks broken to end users.
- Does the Version field need to follow a specific format?
- No strict format is enforced, but a simple numeric scheme like 1.0.0 is standard practice and works well with WordPress's built-in update mechanisms if you later distribute updates.