The Placer Toolkit alpha has arrived! 🎉
Plenty of changes are coming your way—some big, some breaking, some even nuclear! Beware the changelog…

Bring it on!

Customisation

Placer Toolkit components can be customised at a high level through design tokens. This gives you control over theme controls and general styling. For more advanced customisations, you can make use of CSS parts and custom properties to target individual components.

Colour schemes#

Placer Toolkit offers two built‐in colour schemes—light and dark mode—which allow users to switch colour schemes based on ambient lighting conditions or personal aesthetic preference.

These colour schemes work by defining specific CSS custom properties (primarily colour tokens) that utilise opposite sides of the colour tint scale to ensure optimal contrast in each mode.

The two available colour schemes are:

Light mode (default): Uses dark content on light backgrounds.
Dark mode: Uses light content on dark backgrounds to reduce eye strain in low‐light environments.

You can activate a colour scheme by applying a single class to the appropriate HTML element.

To apply dark mode across the entire page, add the pc-dark class to the root <html> element.

 <!DOCTYPE html>
-<html>
+<html class="pc-dark">
     <head>
         <!-- … -->
     </head>
     <body>
         <!-- … -->
     </body>
 </html>

If you only want dark mode to apply to a specific element, you can apply the pc-dark class directly to that element.

Light mode is the default colour scheme. This means, you do not need to specify a class (like pc-light) to activate it. However, the pc-light class is available should you need it for specific theme‐switching logic or component‐level overrides.

Themes#

Placer Toolkit uses themes to apply a cohesive look and feel across the entire library. Themes are built with a collection of pre‐defined CSS custom properties, which we call design tokens, and you can mix and match styling with 18 unique possibilities to choose from.

To use a theme, simply add a link to the theme’s stylesheet to the <head> of your page. For example, you can add this code snippet alongside the installation code to use the corresponding theme.

Default

Utility

Serene

The Default theme serves as the default theme for Placer Toolkit, therefore, you don’t need to import it separately. But we’ll list the font import again.

<link rel="stylesheet" href="https://fonts.bunny.net/css?family=jetbrains-mono:100,100i,200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i|nunito:200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i,900,900i|playfair-display:400,400i,500,500i,600,600i,700,700i,800,800i,900,900i&display=swap" />

<link rel="stylesheet" href="https://fonts.bunny.net/css?family=ibm-plex-mono:100,100i,200,200i,300,300i,400,400i,500,500i,600,600i,700,700i|inter:100,100i,200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i,900,900i&display=swap" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/styles/themes/utility.css" />

<link rel="stylesheet" href="https://fonts.bunny.net/css?family=lora:400,400i,500,500i,600,600i,700,700i|montserrat:100,100i,200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i,900,900i|source-code-pro:200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i,900,900i&display=swap" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/styles/themes/serene.css" />

Design tokens#

Design tokens are accessed through CSS custom properties that are defined in your theme. Because design tokens live at the page level, they’re prefixed with --pc- to avoid collisions with other libraries.

To customise a design token, simply override it in your stylesheet using a :root block. Here’s an interactive example that changes the accent colour to indigo based on existing design tokens.

:root,
.pc-light {
    --pc-color-primary-fill-quiet: var(--pc-color-indigo-95);
    --pc-color-primary-fill-normal: var(--pc-color-indigo-90);
    --pc-color-primary-fill-loud: var(--pc-color-indigo-50);
    --pc-color-primary-border-quiet: var(--pc-color-indigo-90);
    --pc-color-primary-border-normal: var(--pc-color-indigo-80);
    --pc-color-primary-border-loud: var(--pc-color-indigo-60);
    --pc-color-primary-on-quiet: var(--pc-color-indigo-40);
    --pc-color-primary-on-normal: var(--pc-color-indigo-30);
    --pc-color-primary-on-loud: oklch(100% 0 0);
}

.pc-dark {
    --pc-color-primary-fill-quiet: var(--pc-color-indigo-10);
    --pc-color-primary-fill-normal: var(--pc-color-indigo-20);
    --pc-color-primary-fill-loud: var(--pc-color-indigo-50);
    --pc-color-primary-border-quiet: var(--pc-color-indigo-20);
    --pc-color-primary-border-normal: var(--pc-color-indigo-30);
    --pc-color-primary-border-loud: var(--pc-color-indigo-40);
    --pc-color-primary-on-quiet: var(--pc-color-indigo-60);
    --pc-color-primary-on-normal: var(--pc-color-indigo-70);
    --pc-color-primary-on-loud: oklch(100% 0 0);
}

Many design tokens are described further along in this documentation. For a complete list, refer to the theme and palette files located in the project’s source code under src/styles. It contains all tokens used in Placer Toolkit.

CSS parts#

Whereas design tokens offer a high‐level way to customise the library, CSS parts offer a low‐level to customise individual components. Again, this is done with pure CSS—no preprocessor required.

Placer Toolkit components use a shadow DOM to encapsulate their styles and behaviours. As a result, you can’t simply target their internals with the usual CSS selectors. Instead, components expose “parts” that can be targeted with the CSS part selector, or ::part().

Here’s an example that modifies the button with the tomato-button class.

<pc-button class="tomato-button" pill>
    <span slot="prefix">🍅</span>
    Tomato Button
</pc-button>

<style>
    .tomato-button::part(base) {
        background-color: transparent;
        color: var(--pc-color-neutral-on-normal);
        border: var(--pc-border-width-s) var(--pc-border-style)
            var(--pc-color-neutral-border-normal);
    }

    @media (hover: hover) {
        .tomato-button::part(base):hover {
            background-color: oklch(69.6% 0.195 32.3 / 10%);
            color: oklch(69.6% 0.195 32.3);
            border-color: oklch(69.6% 0.195 32.3);
            scale: 1.05;
        }
    }

    .tomato-button::part(base):active {
        background-color: oklch(69.6% 0.195 32.3 / 20%);
        color: oklch(69.6% 0.195 32.3);
        border-color: oklch(69.6% 0.195 32.3);
        scale: 0.95;
    }
</style>

Code

Edit

At first glance, this approach might seem a bit verbose or even limiting, but it comes with a few important advantages:

Customisations can be made to components with explicit selectors, such as ::part(base), rather than implicit selectors, such as .button > div > span > .icon, that are much more fragile.
The internal structure of a component will likely change as it evolves. By exposing CSS parts through an API, the internals can be reworked without fear of breaking customisations as long as its parts remain intact.
It encourages us to think more about how components are designed and how customisations should be allowed before users can take advantage of them. Once we opt a part into the component’s API, it’s guaranteed to be supported and can’t be removed until a major version of the library is released.

Most (but not all) components expose parts. You can find them in each component’s API documentation under the Parts section.

Custom properties#

For convenience, some components expose CSS custom properties you can override. These are not design tokens, nor do they have the same --pc- prefix since they’re scoped to a component.

You can set custom properties on a component in your stylesheet.

pc-avatar {
    --size: 6rem;
}

This will also work if you need to target a subset of components with a specific class.

pc-avatar.your-class {
    --size: 6rem;
}

Alternatively, you can set them inline directly on the element.

<pc-avatar style="--size: 6rem"></pc-avatar>

Not all components expose CSS custom properties. For those that do, they can be found in the component’s API documentation.

Animations#

Some components use animations, such as when a dialog is shown or hidden. Animations are performed using the Web Animations API rather than CSS. However, you can still customise them through Placer Toolkit’s animation registry. If a component has customisable animations, they’ll be listed in the Animation section of its documentation.

To customise a default animation, use the setDefaultAnimation() method. The function accepts an animation name (found in the component’s docs) and an object with keyframes, options or null to disable the animation.

This example will make all dialogs use a custom show animation.

import { setDefaultAnimation } from "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/utilities/animation-registry.js";

// Change the default animation for all dialogs
setDefaultAnimation("dialog.show", {
    keyframes: [
        { transform: "rotate(-10deg) scale(0.5)", opacity: "0" },
        { transform: "rotate(0deg) scale(1)", opacity: "1" },
    ],
    options: { duration: 500 },
});

To support RTL languages in your animation, you can pass an additional property called rtlKeyframes. This property shares the same type as keyframes and will be automatically used when the component’s directionality is RTL. If rtlKeyframes is not provided, keyframes will be used as a fallback.

If you only want to target a single component, use the setAnimation() method instead. This function accepts an element, an animation name and an object comprised of animation keyframes and options.

In this example, only the target dialog will use the custom show animation.

import { setDefaultAnimation } from "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/utilities/animation-registry.js";

// Change the default animation for a single dialog
const dialog = document.querySelector("#my-dialog");

setDefaultAnimation(dialog, "dialog.show", {
    keyframes: [
        { transform: "rotate(-10deg) scale(0.5)", opacity: "0" },
        { transform: "rotate(0deg) scale(1)", opacity: "1" },
    ],
    options: { duration: 500 },
});

To learn more about creating web animations using the Web Animations API, refer to the documentation for Element.animate().

Animations respect the user’s prefers-reduced-motion setting. When this setting is enabled, animations will not be played. To disable animations for all users, pass in null instead of a keyframes/options object.