Theming a component so it looks like your site

A component renders inside your page, so it should look like your page. There is no WPIntegrate branding inside a component and no watermark — our styling stops at the boundary of our own properties.

What you set

Theme settings live on the component instance, alongside everything else the builder saves. They are not attributes on the element, so changing a theme never means editing a published page.

Brand colour. One colour. It is expanded into a full sixteen-step tonal ramp — the lighter and darker steps needed for hover, pressed, borders and backgrounds are derived from the hue and saturation of the colour you gave, rather than being separate settings you have to keep in tune with each other. Give it your brand colour and the interaction states follow.

Corner radius. A pixel value. Square through to fully rounded.

Typeface. A font family name. The component does not load a webfont for you — it asks for a family, and the visitor’s browser resolves it against the fonts your page has already loaded. Name a family your site actually loads, and the component matches the rest of the page for no extra bytes. Name one it does not, and the browser falls back.

Light, dark, or automatic. Automatic follows the visitor’s own system preference, which is usually what you want if your site does the same.

Some components add controls beyond these — text sizes per tier, a typography scale, and label overrides for changing wording. The component’s own page in the dashboard shows the set it supports.

Two levels

A brand theme set on the account is the default for every component you create. An individual instance can override it. The narrower setting wins, which is what lets one site run a component in the site palette and another instance of the same component in a microsite’s palette.

Custom CSS, and when to reach for it

There is a custom CSS field, and it is the last resort rather than the first. Prefer the theme settings: they are expressed in the component’s own token system, so they survive updates to the component. CSS written against the internal class names of a component is a rule about somebody else’s markup, and markup changes.

Why your site’s CSS can affect a component

Components render into the page itself, not into a shadow root. That is not an oversight — the styling engine underneath them inserts its rules into the document head, and those rules cannot cross a shadow boundary, so a shadow-mounted component would render completely unstyled.

The trade-off is that broad rules on your page reach inside the component. A global * { box-sizing: … } is usually harmless; a blanket button { … } or a div { margin: … } is usually not. If a component renders the right content with the wrong appearance, look for a wide selector on the host page before you look at the theme settings.

Related

• Ways to place a component on the page
• Component error codes: why an embed is showing nothing