How to customize Quantum components?

Learn how to customize Quantum components by taking advantage of different strategies for specific use cases.

1. Quantum utilities

Utilities are the static approach of an architectural philosophy referred by Atomic CSS. Concretely, these are simple HTML classes typically dedicated to a single CSS property, like margin or background-color. They can be used additively to style an HTML element from scratch or to override a style defined in components CSS.

All the Quantum utilities are based on Quantum foundations and provide a set of background color, margin, padding, text color, shadow and font utilities. These utilities are reusable classes that can help you limiting the file’s size and reducing the repeated property-value pairs into single classes. And more importantly, make the Quantum components styles easier to customize.

Utility naming

Quantum utilities are named using a format of .[base]-[value], where [base] is generally the name of the CSS property that the utility targets. The parts of a utility name are separated by a hyphen '-'. For a complete list of the utilities and their bases, you can refer to each utility's documentation page.

• Background color
• Font family
• Font size
• Font weight
• Margin
• Padding
• Shadow
• Text color

Installation

First of all, you can install @qtm/css with this command:

npm

npm install @qtm/css@latest

yarn

yarn add @qtm/css@latest

To import these utilities to your project, you have a few options. You can import all Quantum utilities( colors, margin,...) in your CSS file by using the following code:

@import '@qtm/css/dist/utilities.css';

Alternatively, you can include stylesheet <link/> into your <head/> before all other stylesheets to load our CSS.

<link rel="stylesheet" href="./node_modules/@qtm/css/dist/utilities.css" />

Instead of adding all the utilities, you can import independently one or more sets of utilities classified by CSS property: background color, text color, margin, padding,....

@import '@qtm/css/dist/backgroundColorUtilities.css';
@import '@qtm/css/dist/fontFamilyUtilities.css';
@import '@qtm/css/dist/fontSizeUtilities.css';
@import '@qtm/css/dist/fontWeightUtilities.css';
@import '@qtm/css/dist/marginUtilities.css';
@import '@qtm/css/dist/paddingUtilities.css';
@import '@qtm/css/dist/shadowUtilities.css';
@import '@qtm/css/dist/textColorUtilities.css';

Usages

When using the Quantum utilities from @qtm/css/dist/utilities.css, it's important to note that they all have !important properties. This allows you to easily override an existing style no matter the same cascade layer and origin, without having to write high-specificity CSS selectors.

For example, you would like to change text color of a filled primary button from primary to color-yellow-300 color.

How to proceed:

Very simple, add the text-yellow-300 utility to your element.

Button

<QtmButton>Button</QtmButton>

Button

<QtmButton classes="text-yellow-300">Button</QtmButton>

2. High-specificity CSS selectors

Quantum components can be also customized by using high-specificity CSS selectors. This approach allows you to target specific elements and apply changes without affecting any other elements on the page. However, for using this method effectively, you need to know the exact CSS selectors used for components.

For example, you can use the following code to change the color of a button:

Button

<style>
  .btn-custom.qtm-button.qtm-filled.qtm-primary {
    color: var(--color-yellow-300);
  }
  .dark .btn-custom.qtm-button.qtm-filled.qtm-primary {
    color: var(--color-dark-orange-300);
  }
</style>

<QtmButton classes="btn-custom">Button</QtmButton>

3. Tailwind with Quantum Foundations

The Tailwind framework with the Quantum configuration preset allows you to customize your components with Tailwind utility classes based on the Quantum foundations.

This approach provides not only all Quantum utilities available in @qtm/css/dist/utilities.css, but also various utilities generated by Tailwind such as :

• Layout utilities (display, position ...)
• Flexbox & Grid (flex, flex wrap ...)
• Spacing (padding, margin ...)
• Sizing (width, height ...)
• Typography (font family, font size, text align ...)
• Backgrounds (background clip, background color ...)
• Borders (border radius, border color ...)
• Effects (box shadows, opacity ...)
• Filters (blur, brightness ...)
• Tables (border collapse, border spacing ...)
• Transitions & Animation (transition property, transition duration ...)
• Transforms (scale, rotate ...)
• Interactivity (cursor, poiter events ...)
• SVG (fill, stroke ...)

info

Learning more about Tailwind Quantum preset

tip

To better set up your Tailwind config with the Quantum configuration preset, we recommend to read the Tailwind configuration and the Tailwind preset documentations

Installation

npm install -D tailwindcss @qtm/tailwind-preset

then,

npx tailwindcss init

and import the quantum tailwind preset into the tailwind config file.

//tailwind.config.js
const tdsPreset = require('@qtm/tailwind-preset');

/** @type {import('tailwindcss').Config} */
module.exports = {
  presets: [tdsPreset],
  content: ['./src/**/*.{html,js}'],
  theme: {
    extend: {},
  },
  important: true, // needed to override quantum components
  darkMode: 'class', // needed to support dark mode
  plugins: [],
};

Usage

For example, you would like to change text color of a filled primary button for the default and the hover states. Additionally, you would like to make the button rounded. You can achieve this really fast, by using the following CSS classes:

Button

<QtmButton classes="text-yellow-300 hover:text-yellow-500 dark:text-dark-orange-300 dark:hover:text-dark-orange-500 rounded-full">
  Button
</QtmButton>