Common Props

All components in @codedazur/fusion-ui share a set of common properties, largely inherited from a foundational Box component or standard React patterns.

HTML Attributes

First of all, all Fusion components support the standard HTML attributes that are applicable to the underlying HTML element.

<Text
  id="my-text"
  data-testid="my-text"
  aria-label="My Text"
  onMouseEnter={() => alert("Text hovered!")}
>

The className Prop

The standard className prop on all Fusion components has been augmented to support complex class name arrays or objects.

<Box className={["foo", { bar: !!someCondition }]}>

import { classNames } from "@codedazur/fusion-ui";
 
<div className={classNames("foo", { bar: !!someCondition })}>

The as Prop

All Fusion components support an as prop, which allows you to change the underlying HTML element that gets rendered, while retaining the component’s styles and behavior. For example, you could render a Button as an <a> tag if it’s primarily a navigation link.

<Text as="h1">This Text renders as an H1 element.</Text>

Sprinkle Props

All Fusion components derive from the Box component, which grants them access to a powerful and optimized set of “sprinkle props”. You can use these to apply common styles directly as component properties, using your design system tokens.

<Box
  padding={{ horizontal: 400, vertical: 300 }}
  background={{ color: "surface.container.low" }}
  border={{ radius: 100 }}
>
  This element is styled using sprinkle props.
</Box>

These props cover a wide range of CSS properties, allowing you to control everything from layout and spacing (e.g., padding, margin, and flexbox properties like gap) to visual styling (e.g., background, border, and text properties).

Why Sprinkle Props

Sprinkle props are a powerful way to apply styles to your components. They are designed to be easy to use and understand, and to reduce the amount of custom CSS you need to write.

• Token-Based: Values are typically design token keys, reducing the amount of custom CSS you need to write.
• Type-Safe: TypeScript helps ensure you’re using valid props and token keys.
• Responsive: Sprinkle props can be responsive with minimal effort (see below).
• Optimized: Sprinkles generate atomic CSS classes, leading to more efficient styling than traditional CSS.

Responsive Sprinkle Props

Sprinkle props are responsive. You can define different values for different breakpoints (i.e., base, small, medium, large).

<Flex gap={400} direction={{ base: "column", small: "row" }}>
  <Button padding={{ horizontal: { medium: 800 } }}>
    Responsive Padding
  </Button>
  <Button display={{ medium: "none" }}>
    Mobile Only
  </Button>
</Flex>

Alternatives

Although sprinkle props are the preferred way to apply styles to your components, you are certainly not required to use them. There are several alternative ways to apply styles to your components.

For example, you can use the sprinkle functions directly and apply them to any element’s class name.

<div className={classNames([
  padding({ horizontal: 400, vertical: 200 }),
  background({ color: "surface.container.low" }),
  border({ radius: 100 })
])}>
  This element is styled using sprinkle functions.
</div>

Or, you can use the sprinkle functions in a Vanilla Extract style definition.

import { style } from "@vanilla-extract/css";
import { background } from "@codedazur/fusion-ui/style";
 
export const myStyle = style([
  background({ color: "surface.container.base" }),
  border({ color: "surface.outline", width: 100, radius: 300 }),
  padding(400),
]);

If you don’t want to use the sprinkles at all, or if you have a use case that is not covered by the sprinkles, you can of course use the tokens directly.

import { style } from "@vanilla-extract/css";
import { tokens } from "@codedazur/fusion-ui/style";
 
export const myStyle = style({
  backgroundColor: tokens.semantic.colors.surface.container.base,
  borderColor: tokens.semantic.colors.surface.outline,
  borderWidth: tokens.primitive.borderWidth[100],
  borderRadius: tokens.primitive.borderRadius[300],
  padding: tokens.primitive.spacing[400],
});

Finally, you can of course just use plain CSS as well.

import { style } from "@vanilla-extract/css";
 
export const myStyle = style({
  backgroundColor: "#fefefe",
  border: "1px solid #e0e0e0",
  padding: "1rem",
});

And, you can mix and match all of the above techniques as you like.

import { style } from "@vanilla-extract/css";
import { tokens, padding } from "@codedazur/fusion-ui/style";
 
export const myStyle = style([
  {
    backgroundColor: "#fefefe",
    border: "1px solid #e0e0e0",
  },
  padding("400"),
]);

<Box
  constraints={{ maxWidth: 600 }}
  className={[myStyle, margin({ top: 400 })]}
>
  This box uses a combination of sprinkle props, sprinkle functions, and plain
  CSS.
</Box>