Components and Theming

Introduction

The default Catalyst theme is built on a design system of modern React components for use in composable websites, built and maintained by BigCommerce.

This component system is designed specifically for ecommerce, providing beautiful, out-of-the-box UI for every part of the commerce experience. The library includes general, low-level components like buttons and accordions, as well as orchestrating these lower level components into more sophisticated presentations like product cards, product lists, and a site header.

The component library leverages modern patterns and the latest features of Next.js, and it is optimized for fast performance. The clean, practical prop interfaces of its components make them flexible and reusable in any context where they’re needed within your UI.

The look and feel of your storefront is easily style-able without the need for modifying component code. However, all theme components are also included directly in your project, ready to be customized to suit your own requirements.

File Structure

The theme components are found in vibes/soul within your Catalyst project. This includes several major sub-sections:

• form: Contains streamlined implementations of common form controls
• lib: Contains general utilities that are used within various components
• primitives: Contains unique component implementations for various pieces of UI, from the smallest general building blocks like buttons to more complex UI like accordions and product cards
• sections: Components in this area represent larger UI sections built from the more primitive components or other sections, such as a “product detail” section built by orchestrating together a product gallery component, rating component, product form component, etc.

These components are used throughout Catalyst to build the primary UI.

Styling Components

All components within Catalyst are styled using Tailwind CSS, a CSS framework that enables rapid and reliable styling and visual layouts with a system of utility classes.

The following is a limited example from the core components:

<div
  className={clsx(
    'pl-5 pt-5 text-4xl font-bold opacity-25 @xs:text-7xl'
  )}
>
  {title}
</div>

This includes Tailwind classes controlling padding, text size, font weight, etc.

Catalyst components utilize a common set of global utility classes to ensure a consistent look and feel. CSS variables are also often used to offer component-specific theming on a global or per-use basis. The following is an example of utilizing the Card component with a custom text color:

<div
  style={{
    '--card-light-text': '#777777',
  } as CSSProperties}
>
  <Card
    href="..."
    title="..."
  />
</div>

To customize the look and feel of your storefront without changing the basic structure and behavior of its components, the following key files control global Tailwind and CSS configuration:

• globals.css: Defines global CSS variables, which are used for global Tailwind config, can override styles for specific component types, and can also include arbitrary variables for use in your own components
• tailwind.config.js: Defines Tailwind configuration including general typography styles, a common color palette, standard fonts and font sizes, and more
• app/fonts.ts: Loads and defines the common fonts used in Tailwind configuration

Resources

• Tailwind CSS