Using CSS

As we’ve seen earlier, in addition to your React components with TypeScript, you can also create CSS files to style your components.

There are a few ways to include CSS files in your extensions:

• Using cssmodules to access classes through the object automatically generated by the bundler.
• Using import to globally access the classes (e.g., className='btn').

Premises

Using CSS is recommended exclusively for styling your extensions. CSS files have access to the global scope where they are loaded, meaning they can technically target and style other elements of the Sales App core. However, using global CSS to style elements outside of your extension, relying on selectors like tag, class, id, or any other combination not specific to the extension, is discouraged for the following reasons:

• Future releases may include sandboxing mechanisms that isolate CSS and/or extensions from the core application’s global context (e.g., DOM).
• Using selectors like classes or IDs on core Sales App elements (e.g., the “Continue” button, the cart list, header, logo) is not feasible, as Sales App generates unique IDs for classes applied to its elements.
• Relying on the markup to create selectors with the goal of customizing the core Sales App is risky, as the markup may change with core updates (e.g., adding or removing elements in the DOM).

With that in mind, CSS should only be used for styling the extension itself. Any styling applied to core elements is subject to breaking changes due to bug fixes, new features, and other updates.

Tip

Visual changes, such as the primary brand color, are currently done through configuration. Other visual customizations (like fonts, borders, etc.) will be possible in future releases.

CSS Modules Recommended

Using CSS Modules is a recommended approach because it ensures that class names are scoped locally to the component, avoiding potential conflicts with other styles in the global namespace.

With CSS Modules, classes are imported as an object, and you can apply them to your components dynamically, ensuring a clean separation of styles.

Example:

CustomMessage.tsx

CustomMessage.tsx

import styles from './custom-message.module.css';

export const CustomMessage = () => {
  return (
    <p className={styles.footer}>
      Extension example
    </p>
  );
};

custom-message.module.css

custom-message.module.css

.custom-message {
  background-color: black;
  color: white;
}

Tip

When using CSS Modules, the bundler automatically creates unique class names, so there’s no need to worry about class name collisions.

Imports Not recommended

When using imports, you will include .css files in the relevant TypeScript file. You can either create a single file and import it once in src/index.tsx, or create component-specific files and import them in the component’s file.

A single CSS file

src/index.tsx

import { defineExtensions } from '@vtex/sales-app'
import './styles.css'

Multiple CSS files

CustomMessage.tsx

import './custom-message.css'
const CustomMessage = () => {...}

CustomTotalizer.tsx

import './custom-totalizer.css'
const CustomTotalizer = () => {...}

Caution

However, regardless of how you choose to import, this technique generates globally scoped CSS class names, meaning they can conflict with other extensions you’re styling. On the other hand, Sales App itself generates classes with unique IDs, so there is no conflict with the core.

CSS Variables

For the full list of available variables and usage examples, visit the CSS Variables page.