PlumaProvider

PlumaProvider provides context to all Pluma components. More specifically, it:

• Provides a theme context
• Adds the theme's CSS variables
• Imports and adds icon sprites
• Provides additional global or component-specific flags

It is required to render PlumaProvider at the root of your app.

Theming

A theme object provides all the tokens and styles for a theme. It can be passed to PlumaProvider as the theme prop:

import { defaultTheme } from '@customerio/pluma-components/css';

export function App() {
	return <PlumaProvider theme={defaultTheme}>...</PlumaProvider>;
}

The theme object must implement the PlumaTheme or PartialPlumaTheme type, both of which are based on the token output generated from our base tokens.

PlumaProvider will render a div element and attach the theme's class name to it, which adds all the theme's CSS variables to that container.

If you need to add additional classes to that element, add them to PlumaProvider, which will forward them to the div:

<PlumaProvider theme={defaultTheme} className="my-app-root-class">
	...
</PlumaProvider>

If you don't need to render the theme container - for example, when using Pluma Components inside a microfrontend where the root app already has a theme - you can prevent PlumaProvider from rendering it with the shouldRenderContainer argument:

<PlumaProvider theme={inheritedTheme} shouldRenderContainer={false}>
	...
</PlumaProvider>

Note that it is still recommended to provide a theme, even to a PlumaProvider within a nested microfrontend. You should retrieve the theme from the root app and pass it into the microfrontends, in case any code or component needs to access the theme's variables via context.

Color scheme

In addition to the explicit theme prop, PlumaProvider accepts a colorScheme prop that picks between light and dark tokens at runtime. It accepts:

• 'light' (default) — apply the light tokens.
• 'dark' — apply the dark tokens.
• 'auto' — follow the user's system preference via prefers-color-scheme. The Provider listens for changes and updates dynamically.

To use colorScheme you also pass themes — an object with light and/or dark theme objects. The Provider picks the matching one based on the resolved scheme:

import { lightTheme, darkTheme } from '@customerio/pluma-components/css';

export function App() {
	return (
		<PlumaProvider
			colorScheme="auto"
			themes={{ light: lightTheme, dark: darkTheme }}
		>
			...
		</PlumaProvider>
	);
}

<PlumaProvider
	@colorScheme='auto'
	@themes={{hash light=this.lightTheme dark=this.darkTheme}}
>
	...
</PlumaProvider>

themes is consumer-supplied so callers that always pass their own theme don't pull the canonical light/dark theme CSS into their bundle. Import the canonical themes from @customerio/pluma-components/css if you want the standard light/dark behavior.

When the theme prop is provided, colorScheme and themes are ignored — theme always wins as an explicit override.

Reading the current scheme

Three contexts are exposed for descendants:

• PlumaThemeContext (usePlumaTheme() in React, @consume(PlumaThemeContext) in Ember) — the effective theme object.
• PlumaColorSchemeContext (usePlumaColorScheme() / @consume(PlumaColorSchemeContext)) — the resolved scheme, always 'light' or 'dark'. When colorScheme is 'auto', this is the system-resolved value. Use this for conditional logic that needs a concrete scheme.
• PlumaColorSchemePreferenceContext (usePlumaColorSchemePreference() / @consume(PlumaColorSchemePreferenceContext)) — the unresolved preference ('auto' | 'light' | 'dark'). Used by components like Image that need to decide whether to swap variants via prefers-color-scheme media queries (auto) or by filtering upfront (explicit).

Nested Providers

themes propagates through context, so a nested PlumaProvider can specify only colorScheme and resolve against an ancestor's themes:

<PlumaProvider colorScheme="auto" themes={{ light: lightTheme, dark: darkTheme }}>
	{/* follows the user's system preference */}
	<Outlet />

	<PlumaProvider colorScheme="dark">
		{/* forced to dark, resolved against the ancestor's `themes.dark` */}
		<DarkOnlyArea />
	</PlumaProvider>
</PlumaProvider>

When a nested PlumaProvider has colorScheme (and themes are in scope, own or inherited), the matching variant wins over a theme inherited from PlumaThemeContext. To extend the inherited themes — overriding e.g. only dark — pass a partial themes object: it's merged over the inherited one, so the unaltered variants stay accessible.

Icons

If you're planning to use the Icon component, you'll need to pass in an IconManager instance. The IconManager class comes from the @customerio/pluma-icons package.

import { defaultTheme } from '@customerio/pluma-components/css';
import { IconManager } from '@customerio/pluma-icons';

// Instantiate the IconManager
const iconManager = new IconManager();

export function App() {
	return <PlumaProvider theme={defaultTheme} iconManager={iconManager}>...</PlumaProvider>;
}

An IconManager is responsible for importing the icon SVG sprite sheet, and attaching it to the document body. When PlumaProvider receives an IconManager, PlumaProvider will instruct IconManager to load and attach the sprites when the app first renders.

The sprites only get loaded and attached when PlumaProvider renders, so it's safe to instantiate the IconManager instance outside of components or effects. Additionally, a single IconManager instance will only attach sprites once, even if called multiple times.

In microfrontends, only the root app needs to provide an IconManager. The sprites are attached to the document body, and are then available globally, to all embedded microfrontends.

Similar to the theme object, it is recommended to pass in the IconManager instance from the root app's context into the microfrontend PlumaProvider, in case any components need to reference the IconManager.

Client side routing

Pluma includes link components such as PlainLink and Link, which may perform navigation events. By default, those components render plain a tags, which would use the browser's native navigation, which cause a full page reload.

In a single page application, there is typically a routing library which takes over linking and issues navigation events internally, without refreshing the whole page. While Pluma itself is agnostic towards what an app's routing setup is, it allows customizing the link component, so that consuming apps may still navigate correctly.

A custom component can be defined on PlumaProvider through the linkComponent prop.

There are a few basic requirements the component must adhere to in order to work correctly:

• it must implement the LinkComponent type
  • in React: import type { LinkComponent } from '@customerio/pluma-components/react';
  • in Ember: import type { PlumaLinkComponent, PlumaLinkComponentSignature } from '@customerio/pluma-components/ember';
• in React, the component must use forwardRef
• by implementing the type, the component must accept at least these two arguments:
  • href - a string, the target URL for the router navigation
  • replace - a boolean, which indicates that the transition should replaceState rather than pushState
• it's recommended the component render a regular a tag, and not a Box component, as Pluma already wraps the component in Boxes internally

In React with React Router, this setup might look like:

import { forwardRef } from "react";
import { Link as ReactRouterLink, Outlet } from 'react-router-dom';
import { PlumaProvider } from '@customerio/pluma-components/react';
import type { LinkComponent } from '@customerio/pluma-components/react';

const LinkDefinition = forwardRef(function(props, ref) {
	const { href, replace, ...restProps } = props;
	return <ReactRouterLink to={href} replace={replace} {...restProps} ref={ref} />;
}) as LinkComponent;

export function App() {
	return (
		<PlumaProvider linkComponent={LinkDefinition}>
			<Outlet />
		</PlumaProvider>
	);
}

In Ember, it might look like:

// app/components/link-definition.ts
import Component from '@glimmer/component';
import { service } from '@ember/service';
import RouterService from '@ember/routing/router-service';
import type { PlumaLinkComponentSignature } from '@customerio/pluma-components/ember';

export default class LinkDefinition extends Component<PlumaLinkComponentSignature> {
	@service('router') router!: RouterService;

	onClick = (event: MouseEvent) => {
		event.preventDefault();
		const targetHref = event.currentTarget.href.replace(window.location.origin, '');
		this.router.transitionTo(targetHref);
	}
}

{{!-- app/components/link-definition.hbs  --}}
<a ...attributes href={{@href}} {{on "click" this.onClick}}>{{yield}}</a>

// app/controllers/application.ts
import Controller from '@ember/controller';
import LinkDefinition from 'my-app/components/link-definition';

export default class ApplicationController extends Controller {
	LinkDefinition = LinkDefinition;
}

{{!-- app/templates/application.hbs  --}}
<PlumaProvider @linkComponent={{this.LinkDefinition}}>
	{{outlet}}
</PlumaProvider>

Note: In Ember apps, we typically use the LinkTo component for router links. That component accepts arguments like @model and @route instead of a @href string, which is different from what we require for Pluma's link component.

Our recommendation is to use an addon like ember-link or a custom helper to generate the href string. Invoking a PlumaLink component might then look like:

<PlumaLink
	@href={{route-href
		route="campaigns.campaign"
		model=this.model.id
	}}
>
	View campaign
</PlumaLink>

While the helper might be:

import Helper from '@ember/component/helper';
import { inject as service } from '@ember/service';
import type RouterService from '@ember/routing/router-service';

export default class extends Helper {
	@service router!: RouterService;

	compute(_, { route, model }) {
		return this.router.urlFor(route, model);
	}
}

Component config

Certain components may expose a set of default or configuration props that can be set from the PlumaProvider level. For example, the Snackbar component's close timeout can be modified like this.

PlumaProvider accepts a componentConfig prop, which is an object with component names for keys. Please refer to the individual component docs for more information on what configuration is available.

Component flags

These flags may be used by specific components to alter their behavior. Certain components can behave or render differently based on these flags. These are all the currently available flags:

• unsafe_useLegacyButton
• unsafe_useLegacyTextField
• unsafe_useLegacyTextArea
• unsafe_useLegacySelect
• unsafe_useLegacyLink