Puck is the open-source visual editor for React, empowering the next generation of page builders and no-code products. Give us a star on GitHub! ⭐️
When integrating Puck into your page-building product, a common requirement is to allow your users to centrally manage the theme of the page without having to make adjustments to every component.
For example: users need a way to manage font styles globally—even for components already added to the page. Here’s how that could look in action:
Since Puck is just a React component, there are lots of ways to solve this problem (as well as managing other, more complex state). For this article, I’ll focus on one of the simplest yet most powerful approaches—CSS properties. Let’s dive in!
For this tutorial, I’ll assume you have a basic understanding of Puck and its functionality. If you’re new to Puck, don’t worry—you’re still welcome to follow along! However, I recommend checking the getting started guide to familiarize yourself with the fundamentals.
I’ll start by setting up a project using Vite’s scaffolding script. You’re welcome to follow along or skip this section if you already have a project with Puck.
If you’re using Next.js or Remix you could also use one of the official Puck recipes for setting up your project.
To get started, open your terminal and run the following commands to create a new Vite project:
npm create vite@latest puck-global-themes -- --template react
cd puck-global-themes
npm install
Next, install the Puck package:
npm i @measured/puck --save
When you start a new project with Vite, it’ll come with some default styles that will clash with Puck’s. To fix this, delete src/index.css
and src/App.css
, then remove their imports from src/main.jsx
and src/App.jsx
:
// main.jsx
import "./index.css"; // Remove this line
// App.jsx
import "./App.css"; // Remove this line
With the basic project structure ready, head over to your src/App.jsx
file and replace its contents with the code below. This will set up Puck with a basic config for dragging and dropping Heading and Paragraph components:
Note that, for the sake of simplicity I’m using in-line styling in this example
// App.jsx
import { Puck } from "@measured/puck";
import "@measured/puck/puck.css";
// The configs for each of your draggable components
// Ideally you would pull each of these to their own files
const headingConfig = {
defaultProps: {
title: "Title",
},
fields: {
title: {
type: "text",
},
},
render: ({ title }) => {
return (
<div>
<h1>{title}</h1>
</div>
);
},
};
const paragraphConfig = {
defaultProps: {
content: "This is a paragraph...",
},
fields: {
content: {
type: "textarea",
},
},
render: ({ content }) => {
return (
<div>
<p>{content}</p>
</div>
);
},
};
// The Puck configuration object
const config = {
components: {
Heading: headingConfig,
Paragraph: paragraphConfig,
},
root: {
render: ({ children }) => {
return (
<main
style={{ fontFamily: "Arial, Helvetica, sans-serif", padding: 32 }}
>
{children}
</main>
);
},
},
};
// Your editor component
const App = () => {
return <Puck config={config} data={{}} />;
};
export default App;
Finally, run the application in development mode, navigate to http://localhost:5173, and check that everything is working as expected:
npm run dev
Awesome! Now that you have a foundation to build on, let’s add theming for your users.
As I mentioned before, CSS custom properties are an excellent choice for adding interactive theming to your editor. Why is this a great approach? Because it’s lightweight, doesn’t require external dependencies, and is (for the most part) handled natively by the browser.
To add dynamic theming with CSS properties you’ll need to define your theme variables as properties at some parent of the component that needs them. This could be Puck’s root
component or any other parent component in your editor’s hierarchy, it really doesn’t matter as long as you define them and then read them where you need using the var
CSS function.
For this tutorial, I’ll focus on using Puck’s root
component so that users are able to set font size and color for headings and paragraphs in a single place at the top level of the editor:
Start by defining an object to centralize all the CSS variables names. This will improve consistency and save you from the rabbit hole of debugging issues caused by mistyped property names in CSS.
Pro tip: If you’re using TypeScript you could use an enum instead of an object to get additional type safety
// App.jsx
// The names for each one of the CSS variables
const SharedCSSVars = {
fontColor: "--font-color",
headingFontSize: "--heading-font-size",
paragraphFontSize: "--paragraph-font-size",
};
Next, update the root
config to include the props and fields for the theme variables. This will allow users to update the custom properties directly from within the root fields of the editor.
To do this, you’ll need to define the fields for the new root props and their default values:
// The Puck configuration object
const config = {
components: {
//... existing components
},
root: {
// The default values for your CSS variables
defaultProps: {
fontColor: "#000000",
headingFontSize: 32,
paragraphFontSize: 24,
},
// The fields for your CSS variables
fields: {
fontColor: {
label: "Font color (hex)",
type: "text",
},
headingFontSize: {
label: "Heading font size (px)",
type: "number",
},
paragraphFontSize: {
label: "Paragraph font size (px)",
type: "number",
},
},
//... the root's render function
},
};
After that, in the root’s render function, read the custom properties from the props and pass them to the root element as CSS variables.
// The Puck configuration object
const config = {
components: {
//... existing components
},
root: {
//... the root fields configuration
render: ({ children, fontColor, headingFontSize, paragraphFontSize }) => {
return (
<main
style={{
fontFamily: "Arial, Helvetica, sans-serif",
padding: 32,
// The new variables using our names object and the new props
[SharedCSSVars.fontColor]: fontColor,
[SharedCSSVars.headingFontSize]: `${headingFontSize}px`,
[SharedCSSVars.paragraphFontSize]: `${paragraphFontSize}px`,
}}
>
{children}
</main>
);
},
},
};
If you now go to the editor, you should see the new fields at the root level for each one of the props. There is no visual feedback yet, but if you inspect the styles of the editor’s root, you will see the variables being set with every change you make to the fields.
Finally, access the theme variables in the components you need by using the var
CSS function in your styles.
In our example, you’ll add them in the headingConfig
and the paragraphConfig
:
const headingConfig = {
//... The heading fields configuration
render: ({ title }) => {
return (
<div>
<h1
style={{
// Here we are reading the shared styles for the headers
color: `var(${SharedCSSVars.fontColor})`,
fontSize: `var(${SharedCSSVars.headingFontSize})`,
}}
>
{title}
</h1>
</div>
);
},
};
const paragraphConfig = {
//... The paragraph fields configuration
render: ({ content }) => {
return (
<div>
<p
style={{
// Here we are reading the shared styles for the paragraphs
color: `var(${SharedCSSVars.fontColor})`,
fontSize: `var(${SharedCSSVars.paragraphFontSize})`,
}}
>
{content}
</p>
</div>
);
},
};
If you return to the editor, drag and drop some headings and paragraphs, and then modify the fields at the root level, you’ll notice that all the headings and paragraphs update to reflect those changes:
🥳 And that’s it! Your users are now able to define a theme seamlessly applied across different components in their pages.
✅ Pros:
❌ Cons:
Depending on your specific use case, there are plenty of ways to take your editor theming even further:
Heading
component that, if provided, would redefine the CSS property specifically for that h1
element.I hope this tutorial has empowered you to leverage CSS variables for dynamic theming in Puck-powered page builders. The open-source developer community is at the heart of Puck’s evolution, and I can’t wait to see the innovative apps you create!
We’re dedicated to pushing Puck’s capabilities even further, with a constant stream of new features, including a revolutionary drag-and-drop engine for complex grids and layouts launching imminently, and a suite of new plugins on the horizon.
So, if Puck has inspired you or if you’d like to stay up to date with the latest features, here’s how you can get involved:
If you’re interested in learning more about Puck, check out the demo or read the docs. If you like what you see, please give us a star on GitHub to help others find Puck too!