Component Variants

A variant is a named set of props that you apply to a SmartCommon component to modify its appearance without overriding it on every use. This is the mechanism that allows you to have a "rounded button" or a "compact list" throughout the application without repeating Tailwind classes.

Anatomy of a Variant

A variant is an object whose keys describe the component's internal elements.

const rounded = {
  buttonProps: {
    className: "p-app-base rounded-full",
  },
};

Two forms of keys, recognized by their writing:

Uppercase keys are merged recursively: a Button variant can therefore control the Spinner it displays during loading.

const outlined = {
  buttonProps: {
    className: "text-gray-800 bg-white border",
  },
  Spinner: {
    spinnerProps: {
      className: "border-primary border-l-secondary",
    },
  },
};

To know the available keys on a component, look at the mergeProps("...") calls in its source: each corresponds to a variant key. For Button: button, label, icon, badge and the sub-component Spinner.

Apply a Variant

The variant prop accepts three forms, combinable:

// 1. By name (native variant or declared in configuration)
<Button variant="rounded" />

// 2. As an object, directly
<Button variant={{ buttonProps: { className: "rounded-full" } }} />

// 3. As an array, applied from left to right
<Button variant={["rounded", "uppercase", { labelProps: { className: "text-xs" } }]} />

Order and Merge Rules

Sources are applied in this order, the last one wins:

• the variant of the active theme, if it designates one for this component
• the entries of the variant prop, in the order of the array
• the props passed directly to the component

The merge follows three rules depending on the property:

A className or style value can also be a function. It receives the parameters published by the component via setParams, which allows a style dependent on the internal state.

Native Variants

SmartCommon currently provides five native variants, all for Button:

<Button variant="outlined">Cancel</Button>
<Button variant={["rounded", "uppercase"]}>Confirm</Button>

Custom Variants

Your application's own variants are declared in the configuration passed to the Provider, under components.variants, indexed by component name and then by variant name.

// src/appConfig.js
export const appConfig = {
  components: {
    variants: {
      Button: {
        danger: {
          buttonProps: {
            className: "bg-red-600 text-white hover:bg-red-700",
          },
        },
        ghost: {
          buttonProps: {
            className: "bg-transparent border-none shadow-none",
          },
        },
      },
      ListItem: {
        compact: {
          itemProps: { className: "py-1 text-sm" },
        },
      },
    },
  },
};

// src/main.jsx
<Provider config={appConfig}>
  <Router />
</Provider>

They are then used like native variants:

<Button variant="danger">Delete</Button>
<ListItem variant="compact" />

If a custom name uses a native name, both definitions merge.

Themes

A theme associates, for each component, one or more variants to apply by default throughout the application.

components: {
  theme: "compact",
  themes: {
    compact: {
      Button: "rounded",
      ListItem: ["compact", "borderless"],
    },
  },
}

The theme's variant is applied before the variant prop, which can therefore override it punctually.

Components that Accept Variants

More than 70 components use useVariantMerger and therefore accept a variant prop.

Accept Variants in Your Own Component

An application component can use the same mechanism, with useVariantMerger.

import { useVariantMerger } from '@cap-rel/smartcommon';

export const MyCard = (props) => {
  const { variantProps, mergeProps, setParams } = useVariantMerger("MyCard", props);

  const { title, children } = variantProps;

  return (
    <div {...mergeProps("card", props => ({
      ...props,
      className: "rounded-lg border p-4",
    }))}>
      <h3 {...mergeProps("title", props => ({
        ...props,
        className: "font-semibold",
      }))}>
        {title}
      </h3>
      {children}
    </div>
  );
};

What to remember:

• the first argument of useVariantMerger is the component key, the one that will be used in the configuration
• variantProps contains the props after merging: read your business props here, not props directly
• each mergeProps("<key>", ...) creates a hook point for variants
• an uppercase key (mergeProps("Spinner", ...)) designates a sub-component and merges recursively

Pitfalls to Know

See Also

• SmartCommon - list of components
• Themes - light and dark mode, CSS variables
• Provider Configuration
• Components and Pages