Latest workshop recording now available
Watch now
← Back to all how-tos

Customize React Bricks

Configure React Bricks

Understand what lives in the React Bricks config file, what you usually customize first, and where to go for deeper docs.

Estimated time: 7 minRaw Markdown

In this how-to, you'll learn what the React Bricks configuration file is for and what kinds of things you can customize there.

The official docs page is mostly a reference of available properties. This guide gives it a bit more shape, so you can quickly understand what is possible and where to go next.

Docs reference: Customize React Bricks

Where configuration usually happens

In starter projects, React Bricks configuration usually lives in:

/react-bricks/config.ts

This is the place where you connect:

  • your app identity and API settings
  • your bricks and page types
  • the admin interface branding
  • editor behavior and feature flags
  • CSS-related integration details

Many of these values are scaffolded for you by the starter, especially framework-specific ones like routing and navigation.

So in practice, most teams touch this file when they want to:

  • change the admin UI branding
  • enable or disable CMS features
  • adjust how the editor behaves
  • switch environments

The actual bricks and page types are usually defined in dedicated files such as:

/react-bricks/bricks/index.ts
/react-bricks/pageTypes.ts

and then imported into config.ts.

Think of config.ts in 5 groups

The official docs split the configuration object into 5 buckets. That is a good mental model:

  1. main CMS configuration
  2. environment settings
  3. UI configuration
  4. feature flags
  5. CSS-related settings

If you're wondering "can React Bricks do this?", the answer is often "yes, and the switch probably lives in one of those 5 groups".

1. Main CMS configuration

This group defines the content model and the editor capabilities available to your team.

The most important properties here are:

  • bricks: the bricks, themes, and categories editors can add
  • pageTypes: the kinds of pages or entities your project supports
  • customFields: global page-level fields available across the app and shown in the "Page" sidebar tab
  • permissions: fine-grained control over what users can do

This is the part of the config you change when you want to shape the CMS around your project.

For example:

  • add a new custom brick
  • organize bricks into themes and categories
  • create a page type for blog posts, products, or layout entities
  • add global page-level fields like SKU, subtitle, or SEO values
  • restrict actions for certain users or roles

Unlike page-type customFields, these are defined once in the React Bricks config and are available across the app. Historically, customFields started as global, but today most projects add them directly on the page type where they are needed.

Helpful pointers:

Docs reference: Custom Fields

2. Environment settings

These settings wire React Bricks into your app and runtime environment.

This includes properties such as:

  • appId and apiKey
  • environment
  • renderLocalLink
  • navigate
  • loginPath, editorPath, playgroundPath, appSettingsPath, previewPath
  • appRootElement
  • rtlLanguages

Most starters already configure the routing-related properties for the chosen framework, so teams usually leave them alone unless they are customizing the admin route structure.

The main property you are likely to revisit later is:

  • environment, if you want a separate content branch for development, staging, campaign work, or a v2 site

That is useful when you want content isolation without creating a whole separate React Bricks app.

Docs reference: Multiple Environments

3. UI configuration

This group controls how the admin interface looks and how some editing tools are presented.

Common examples are:

  • logo: brand the admin header
  • loginUI: customize the login screen experience
  • getAdminMenu: replace the default admin menu with custom entries
  • clickToEditSide: choose where the click-to-edit control appears
  • responsiveBreakpoints: define the viewport presets available in preview
  • blockIconsPosition: move block action icons (move, add, delete, duplicate) inside or outside the block
  • defaultTheme: choose which brick theme is preselected in the add-brick UI

This is where you make the editor feel more like your product and your workflow.

For example:

  • add your company logo
  • simplify the admin navigation for editors
  • give designers realistic tablet and desktop breakpoints
  • make block actions less intrusive in dense layouts

Helpful pointers:

  • Add your company logo
  • Search the official docs for LoginUI, IMenuItem, and ResponsiveBreakpoint when you need interface-level details

4. Feature flags

These switches enable or disable editor behaviors and optional CMS features.

Some of the most useful ones are:

  • enableAutoSave
  • disableSaveIfInvalidProps
  • enablePreview
  • enablePreviewImage
  • enableUnsplash
  • enableDefaultEmbedBrick
  • allowAccentsInSlugs
  • warningIfLowBattery

This section is especially helpful when you want to tune the editing experience without changing your content model.

For example:

  • enable preview images to make brick insertion more visual
  • disable Unsplash if your team should only use DAM or approved assets
  • block save when a validated prop is invalid
  • turn off the default embed brick if you want tighter control over embeds

If you enable preview images, remember that bricks also need previewImageUrl in their schema.

Helpful pointer:

Docs reference: Embed Pages

5. CSS-related settings

These settings help the editor match your front-end styling setup more closely.

The main ones are:

  • contentClassName
  • isDarkColorMode
  • toggleColorMode
  • useCssInJs

These matter when your bricks depend on a specific styling context.

For example:

  • contentClassName can apply a wrapper class so typography and spacing in the editor look closer to the real site
  • isDarkColorMode and toggleColorMode let you test dark-mode-aware bricks while editing
  • useCssInJs is important if your project uses a CSS-in-JS solution

This is often the difference between an editor that merely works and one that feels trustworthy to content editors.

A practical example

Here is a simplified example of the kind of things teams often customize first:

import bricks from '@/react-bricks/bricks'
import pageTypes from '@/react-bricks/pageTypes'
 
const permissions = {
  // Example only: add your custom permission rules here
}
 
const config = {
  appId: process.env.NEXT_PUBLIC_REACT_BRICKS_APP_ID!,
  apiKey: process.env.NEXT_PUBLIC_REACT_BRICKS_API_KEY!,
  environment: 'staging',
  bricks,
  pageTypes,
  logo: '/logo.svg',
  contentClassName: 'prose max-w-none',
  responsiveBreakpoints: [
    { label: 'Mobile', width: '375px' },
    { label: 'Tablet', width: '768px' },
    { label: 'Desktop', width: '1280px' },
  ],
  enablePreviewImage: true,
  enableUnsplash: false,
  permissions,
}

How to decide what to customize first

If you're starting a new project, a good order is:

  1. register your bricks and pageTypes
  2. add any customFields the project needs
  3. brand the admin UI with logo and optional loginUI
  4. set feature flags like preview images or Unsplash
  5. revisit environment and CSS integration as the project grows

That usually gets you to a useful editor quickly without overthinking every config option upfront.

Summary

The React Bricks config file is not just setup boilerplate. It is the control panel for how your CMS works.

Use it to define:

  • what editors can create
  • what pages can exist
  • how the admin interface behaves
  • which optional features are enabled
  • how closely the editor should match your front end

When you need the exact property-by-property API, use the official reference: Customize React Bricks