How to add custom CSS to WordPress

Custom CSS is a set of rules of your own that change how your theme draws the site: a color, a font size, the space around a heading, an element you would rather hide. Your rules sit on top of the theme's. Where you put them decides whether they are still there after the theme's next update.

Where to put your CSS

To see which kind of theme you have, open the Appearance menu in the dashboard. A classic theme has Customize there. A block theme has Editor, and WordPress hides the Customizer unless a plugin needs it.

Both boxes keep your CSS in the database, apart from the theme's files. That is why an update does not touch it. The CSS belongs to the theme that was active when you wrote it. WordPress's documentation says CSS added in the Styles panel is cleared when you switch themes, and the Customizer stores its CSS separately for each theme. Copy your rules out before you change theme.

On a classic theme, use the Customizer

.site-title is an example. The names in your theme will differ, and the section on finding a selector shows how to read them.

On a block theme, use the Styles panel

Look through the Styles panel before you write anything. Colors, fonts, spacing and the look of each kind of block can be set there with no CSS, and WordPress's documentation recommends starting with those options. CSS is for what they do not reach.

CSS for one kind of block

Under Styles, then Blocks, choose a block. Its settings include a section called "Additional block CSS". What you write there applies to every block of that type on the site.

WordPress already knows which block you mean, so leave out the selector and the braces and write only the declaration. In the Quote block's box, this line sets every quote in italics:

font-style: italic;

In a child theme's stylesheet

A child theme is a small theme of your own that takes everything from your present theme and holds your changes to it. Its style.css is the place for a stylesheet that has outgrown a box in the dashboard, or one you want to keep as a file and copy between sites. Your rules go below the comment at the top of the file.

.entry-title {
  font-size: 2rem;
}

How to create a WordPress child theme covers making one, and checking that its stylesheet is loaded after the parent theme's.

Why not to edit the theme's own files

An update replaces the theme's files with those of the new version. A rule you added to the theme's own style.css goes with the old file, and nothing warns you. The two boxes and the child theme exist so that you never need to open those files.

If you have already edited them, copy your changes into one of the three places above before the theme's next update.

Find the right selector

A rule has two parts. The selector says which elements the rule applies to. The declarations between the braces say what changes. To write the selector you need the names your theme has given the element, and your browser's developer tools show them.

When a rule does not apply

Inspect the element again and look for your rule in the list.

• Your rule is not there. The selector does not match the element, or you are looking at an old copy of the page. Check the selector for a missing dot or a misspelled name. Then empty the cache of your caching plugin and of your host, and reload.
• Your rule is there with a warning beside a line. The browser does not accept that property or value. Check the spelling.
• Your rule is there with a line through it. Another rule has won.

When two rules set the same property on the same element, the browser picks the one whose selector is more specific. IDs count for most, then classes, then element names. If the two selectors are equally specific, the rule that comes later in the page wins.

So read the selector of the rule that beat yours, and write one that is a step more specific. Adding a class from an element further up the page is usually enough.

/* The theme's rule: one class and one element name */
.entry-content h2 {
  color: #333333;
}

/* Too weak: one element name */
h2 {
  color: #1a4d2e;
}

/* Strong enough: two classes and one element name */
.site-main .entry-content h2 {
  color: #1a4d2e;
}

If your selector matches the theme's exactly and still loses, the theme's rule comes later in the page than yours. That happens with a child theme whose style.css is loaded before the parent's. The fix is to load it after the parent's, which the child theme guide shows.

Writing !important after a value, as in color: #1a4d2e !important;, makes that declaration beat every ordinary one, whatever the selectors. That is also what is wrong with it. The next time you want to change the same thing, only another !important will do. MDN's advice is not to use it to get past specificity. Keep it for the one case that needs it: a style that a plugin or a script writes directly onto the element, which no selector can beat.

How to undo a change

• Customizer: delete the rule from "Additional CSS" and select "Publish".
• Site Editor: delete the rule from "Additional CSS" and save. The same menu has "Reset to defaults", but that takes back every change you made in Styles, not only your CSS.
• Child theme: remove the rule from style.css and upload the file again. Keep a copy of the file from before each edit.

A wrong rule changes how a page looks, and removing the rule puts the page back.

If you would rather send the change than write the CSS, our website edits cover small changes to what is already on the site, and anything larger is quoted as developer time before work starts.