DEV Community: Aaron Reisman

Why Exposing className in React UI Components is an Anti-Pattern

Aaron Reisman — Thu, 05 Jun 2025 18:07:43 +0000

Why Exposing className in React UI Components is an Anti-Pattern

When building reusable React components, one of the most common debates revolves around whether to expose a className prop to consumers. While it might seem like a flexible solution that gives developers maximum control, exposing className directly is actually an anti-pattern that can lead to brittle, unmaintainable code. Here's why you should think twice before adding that className prop to your UI components.

The Tempting Appeal of className

At first glance, exposing className seems like the ultimate flexibility solution:

// Seems flexible, right?
function Button({ children, className, ...props }) {
  return (
    <button className={`btn ${className || ''}`} {...props}>
      {children}
    </button>
  );
}

// Usage
<Button className="my-custom-styles">Click me</Button>

This approach appears to solve the customization problem by letting consumers add their own styles. However, this convenience comes with significant hidden costs.

The Problems with Exposing className

1. Breaks Encapsulation

Components should be black boxes with well-defined interfaces. When you expose className, you're essentially saying "feel free to reach into my internals and modify whatever you want." This breaks the fundamental principle of encapsulation.

// Consumer can now break your component's styling
<Button className="btn-override-everything">
  This might look completely wrong
</Button>

2. Creates Tight Coupling

Exposing className creates a tight coupling between your component's internal CSS structure and the consumer's code. If you need to refactor your component's styling or change CSS frameworks, you risk breaking every consumer who relied on specific class names.

// Your component internally uses Bootstrap
function Alert({ className, children }) {
  return <div className={`alert alert-info ${className}`}>{children}</div>;
}

// Consumer writes CSS that depends on your internal classes
// .alert.my-custom-alert { ... }

// Later, you switch to Tailwind - consumer code breaks!
function Alert({ className, children }) {
  return <div className={`bg-blue-100 p-4 ${className}`}>{children}</div>;
}

3. Unpredictable Styling Conflicts

CSS specificity wars become inevitable when consumers can inject arbitrary classes. Your carefully crafted component styles might be overridden in unexpected ways, leading to inconsistent UI across your application.

// Consumer accidentally overrides critical styles
<Button className="text-red-500">
  {/* Button might lose its intended styling */}
</Button>

4. Poor Developer Experience

Exposing className shifts the burden to consumers to understand your component's internal structure and CSS specificity rules. This creates a poor developer experience and increases the learning curve.

5. Inconsistent Design System

When every consumer can style components arbitrarily, maintaining a consistent design system becomes nearly impossible. Your carefully designed component variants get diluted by one-off customizations.

Better Alternatives

Instead of exposing className, consider these more robust approaches:

1. Comprehensive Variant System

Design your components with a complete set of variants that cover common use cases:

function Button({ 
  variant = 'primary', 
  size = 'medium', 
  disabled = false,
  children 
}) {
  const baseClasses = 'btn';
  const variantClasses = {
    primary: 'btn-primary',
    secondary: 'btn-secondary',
    danger: 'btn-danger'
  };
  const sizeClasses = {
    small: 'btn-sm',
    medium: 'btn-md',
    large: 'btn-lg'
  };

  const className = [
    baseClasses,
    variantClasses[variant],
    sizeClasses[size],
    disabled && 'btn-disabled'
  ].filter(Boolean).join(' ');

  return <button className={className}>{children}</button>;
}

// Usage - clear and intentional
<Button variant="danger" size="large">Delete Account</Button>

2. CSS Custom Properties for Theming

Use CSS custom properties to expose specific, controlled customization points:

function ProgressBar({ progress, color }) {
  return (
    <div 
      className="progress-bar"
      style={{ '--progress-color': color }}
    >
      <div 
        className="progress-fill"
        style={{ width: `${progress}%` }}
      />
    </div>
  );
}

/* CSS */
.progress-bar {
  background: #f0f0f0;
  border-radius: 4px;
  overflow: hidden;
}

.progress-fill {
  background: var(--progress-color, #007bff);
  height: 100%;
  transition: width 0.3s ease;
}

3. Composition Patterns

Use composition to allow customization while maintaining encapsulation:

function Card({ children }) {
  return <div className="card">{children}</div>;
}

function CardHeader({ children }) {
  return <div className="card-header">{children}</div>;
}

function CardBody({ children }) {
  return <div className="card-body">{children}</div>;
}

// Usage - flexible but controlled
<Card>
  <CardHeader>
    <h2>My Title</h2>
  </CardHeader>
  <CardBody>
    <p>Content goes here</p>
  </CardBody>
</Card>

4. Slot-Based Architecture

Implement slots for specific customization points:

function Modal({ title, footer, children }) {
  return (
    <div className="modal">
      <div className="modal-header">
        {title}
      </div>
      <div className="modal-body">
        {children}
      </div>
      {footer && (
        <div className="modal-footer">
          {footer}
        </div>
      )}
    </div>
  );
}

// Usage
<Modal 
  title={<h1>Custom Title</h1>}
  footer={<Button>Save</Button>}
>
  <p>Modal content</p>
</Modal>

When className Might Be Acceptable

There are very limited cases where exposing className might be justified:

Migration Periods

During transitions from legacy systems, className exposure should be treated as technical debt with a clear plan to remove it.

Branded Types for Specific Use Cases

For very specific scenarios like responsive styling, you can use branded types with semantic prop names that hide the className implementation:
Using TypeScript branded types to provide controlled responsive styling with static class references that work with Tailwind's purging:

// Create a branded type for responsive classNames
declare const __brand: unique symbol;
type ResponsiveClassName = string & { [__brand]: 'responsive-className' };

// Static class mappings that Tailwind can detect
export const RESPONSIVE_BUTTON_CLASSES = {
  'sm-md': 'sm:text-sm sm:px-2 md:text-base md:px-4',
  'sm-lg': 'sm:text-sm sm:px-2 lg:text-lg lg:px-6',
  'md-xl': 'sm:text-base sm:px-4 xl:text-xl xl:px-8',
} as const satisfies Record<string, ResponsiveClassName>;

function Button({ 
  children, 
  responsive,
  ...props 
}: {
  children: React.ReactNode;
  responsive?: ResponsiveClassName;
}) {
  return (
    <button className={`btn ${responsive || ''}`} {...props}>
      {children}
    </button>
  );
}

// Valid - using exported mapping directly
<Button responsive={RESPONSIVE_BUTTON_CLASSES['sm-lg']}>
  Responsive Button
</Button>

// TypeScript error - can't use arbitrary strings
<Button responsive="arbitrary-custom-class">
  This won't compile
</Button>

This approach maintains static class references that Tailwind's purging can detect while providing controlled access through exported mappings. All classes are defined statically, ensuring Tailwind includes them in the final bundle.

Even well-intentioned exceptions like "layout components" or "low-level primitives" are anti-patterns that should be avoided. Instead of generic Box or Brick components, create purpose-built layout components with semantic interfaces like HStack, VStack, or Grid with explicit props for spacing, alignment, and distribution. These should be used sparingly and with clear, constrained APIs.

Best Practices for Component APIs

Start Restrictive: Begin with a minimal, opinionated API. You can always add flexibility later, but removing it is a breaking change.
Think in Design Tokens: Expose semantic properties (variant, size, emphasis) rather than visual properties (className, style).
Provide Escape Hatches Carefully: If you must provide customization, do it through controlled mechanisms like CSS custom properties or data attributes.
Document Intentions: Make it clear what customizations are supported and what might break in future versions.

Conclusion

While exposing className might seem like the path of least resistance, it ultimately leads to fragile, tightly-coupled code that's difficult to maintain and evolve. By designing thoughtful component APIs with proper variants, composition patterns, and controlled customization points, you can provide the flexibility developers need while maintaining the integrity and consistency of your design system.

Remember: good component design is about finding the right balance between flexibility and constraints. Your future self (and your teammates) will thank you for choosing the more disciplined approach.

Utility Type for curried functions in TypeScript

Aaron Reisman — Mon, 12 Jun 2023 09:58:07 +0000

Ever need a Type for a curried style function? Here's how you do it!

// Type helper to define curried function
type Func<T extends readonly any[]> = T["length"] extends 0
  ? () => void
  : T["length"] extends 1
  ? () => T[0]
  : (
      x: T[0]
    ) => T extends readonly [infer _, ...infer V]
      ? V["length"] extends 1
        ? V[0]
        : Func<V>
      : never;

// Usage
const func0: Func<[]> = () => undefined;
const func1: Func<[string]> = () => "";
const func2: Func<[string, number]> = (str) => 0;
const func3: Func<[number, boolean, string]> = (num) => (bool) => "";

Understanding and Mastering the CSS Block Formatting Context

Aaron Reisman — Thu, 08 Jun 2023 06:21:36 +0000

Hello, web developers! Today we'll be talking about the Block Formatting Context (BFC) in CSS. It's a fundamental part of how CSS visually renders HTML elements, and understanding it can solve common design problems and simplify your layouts.

What is Block Formatting Context?

In CSS, a Block Formatting Context is a part of the visual CSS rendering of a web page. It's a region in which block boxes are laid out, and floats interact with each other. But, these floats do not interact with elements outside the BFC. This aspect makes BFC a vital concept when designing CSS layouts.

How to create a BFC

There are several properties in CSS to establish a new BFC. Here are some common ways:

Use display with a value of flow-root.
Use float with a value other than none.
Use position with a value of absolute or fixed.
Use overflow with a value other than visible.

.new-bfc {
  display: flow-root;
}

Use Cases for BFC

Now let's explore some common problems that you may face in CSS layouts and how BFC can provide solutions.

Clearing Floats

The Problem

Parent elements can collapse when they contain floated elements because floated elements are taken out of the normal flow.

.container {
}
.left {
  float: left;
  width: 50%;
}
.right {
  float: right;
  width: 50%;
}

In this example, without establishing a BFC, the .container will collapse and won't wrap around .left and .right elements.

The Solution

Establish a BFC, and it will contain these floats.

.container {
  display: flow-root;
}
.left {
  float: left;
  width: 50%;
}
.right {
  float: right;
  width: 50%;
}

Now, the .container will not collapse and correctly enclose the floated children.

Preventing Margin Collapse

The Problem

Margins between adjacent blocks can collapse into each other, forming a single margin that is equal to the larger of the two margins. This is known as margin collapse and can lead to unexpected layout results.

.container {
}
.child {
  margin: 10px 0;
}

In this case, the top and bottom margins of .child can collapse with the margins of elements outside .container.

The Solution

In a BFC, the top margin of an in-flow block-level child is only collapsed with its sibling margins, not with its parent's top margin.

.container {
  display: flow-root;
}
.child {
  margin: 10px 0;
}

With a BFC established on .container, the margin of .child will not collapse with external elements' margins.

Isolating Elements

The Problem

Without a BFC, elements can interact with each other in ways that might not be desirable. For instance, floats and margins can overlap or collapse, which can mess up your layout.

The Solution

Since elements in one BFC don't affect the layout in an adjacent BFC, you can isolate elements, effectively creating a new layout scope.

.isolated-element {
  display: flow-root;
}

With this, the .isolated-element will not interact with surrounding elements.

Wrapping Up

Understanding BFCs in CSS is key to managing complex layouts. They can be your secret weapon to solve layout issues like float containment and margin collapsing. We've just scratched the surface here, so

check out the CSS Spec for more details.

Remember, mastering these CSS concepts will make your life as a web developer easier and your layouts more robust. Happy coding!

If you enjoyed this blog post and found it useful, don't forget to share it with your peers and follow for more content like this.

Simplify Your Mock Data Creation in Tests with @lifeiscontent/to-mocked

Aaron Reisman — Tue, 23 May 2023 20:35:09 +0000

Are you spending too much time constructing complex mock data for your tests? Do you often find yourself ensuring that the mock data accurately reflects the actual types, but feeling it's a tedious and error-prone process? That's where the @lifeiscontent/to-mocked package steps in.

toMocked is a TypeScript utility function designed specifically to streamline the creation of mocked data structures for testing. It was conceived to address the challenges that come with generating intricate mock data. Instead of manually building an entire object for testing, this function allows you to specify the object type and provide only the necessary data that's actually used in the test.

Consider a User type for instance:

type User = {
  name: string;
  age: number;
  address: {
    city: string;
    country: string;
  };
};

You can easily create a mocked user with toMocked:

let user = toMocked<User>({
  name: "Alice",
  age: 30,
  address: {
    city: "CityX",
  },
});

// "Alice"
console.log(user.name);
 // "CityX"
console.log(user.address.city);
 // Throws Error: Property "country" does not exist on...
console.log(user.address.country);

The added benefit of using toMocked is the immediate feedback it provides when application code changes and tests break. It shows how the expectations have changed, making it significantly easier to maintain and update your test suite. Especially when you're using testing frameworks like Vitest, toMocked integrates seamlessly, easing the writing of tests.

Remember, in TypeScript, object represents non-primitive types. So, with toMocked, you're not confined to using plain objects; you can employ arrays and other complex types too.

function toMocked<T extends object>(value: any): T;

Beneath the surface, toMocked capitalizes on the powerful JavaScript Proxy object to define custom behavior for property lookups. It checks if the accessed property exists on the target object. If it doesn't, it throws an error. If it does, the property is retrieved. If the property itself is an object, it gets wrapped in another level of proxy by recursively calling toMocked.

By doing so, it ensures your test data mimics the real thing as closely as possible, and your tests fail fast when expectations change. Therefore, if you're searching for a tool that can simplify your testing process by creating more realistic and maintainable mock data, @lifeiscontent/to-mocked is a worthy contender. Give it a try and notice the difference it brings to your testing workflow.

Need PR review for custom React form component

Aaron Reisman — Sun, 26 Sep 2021 17:58:16 +0000

Hi all, if you have some time before Oct 1st, I'd love some feedback on this PR: https://github.com/lifeiscontent/slider-example/pull/1

⚡️ When using ES6 here's a few great ways to initialize an Array.

Aaron Reisman — Wed, 18 Nov 2020 21:36:29 +0000

React UI Development with Storybook 6.0

Aaron Reisman — Thu, 13 Aug 2020 16:36:15 +0000

I gave a talk on the new Storybook 6.0 and also gave some tips and tricks when building UI Components in React. (the talk was using a beta version so some things have changed in storybook since then, but it's still very relevant)

https://www.youtube.com/watch?v=ZGXuzVipe1U&feature=youtu.be&t=1166

What do you want to learn?

Aaron Reisman — Mon, 27 Jul 2020 23:53:01 +0000

I've been programming for over 20 years and I want to create a course for you!

If you have a few minutes, please fill out my TypeForm so I can know what topics you'd like to learn.

Thank you and have a wonderful day!

https://aaron052812.typeform.com/to/TpCUarCX

Simplifying the mental model of Immediately-invoked Function Expressions in JavaScript

Aaron Reisman — Wed, 13 May 2020 17:53:37 +0000

I'd like to breakdown how Immediately-invoked Function Expression (IIFE) works.

Let's start with some basics.

if I run this code what happens?

(undefined)

the value that is returned from (undefined) is undefined.

what if we replaced that?

(1)

(1) becomes 1

what we're doing is taking a (wrapped) value and returning it.

(x) === x

when passing a function as a value, we can call it.

(function add(x) { return x + x })

becomes

function add(x) { return x + x }

so, if we do

(function add(x) { return x + x })(2)

Our value is a function, and we called that function with the arguments of 2 which the IIFE evaluated to 4.

if we didn't use the parentheses, we'd have to write our code like this:

function add(x) { return x + x }

add(2);

the parentheses handle a step for us, we can define and call a function on 1 line, but if we don't, it results in a syntax error:

function add() { }() // Uncaught SyntaxError: Unexpected token ')'

practical use cases I've seen for IIFE's are:

kicking off the start of code.
invoking a function to get a value to use later.

I'd love to hear your feedback on if this was helpful to you.

Have a good day!

Next.js doesn't hydrate during CSR route change.

Aaron Reisman — Sat, 22 Feb 2020 18:51:53 +0000

Did anyone else not know this about Next.js?

I had just assumed this would be a feature of a SSR + CSR Framework for React.

https://github.com/zeit/next.js/issues/8193

If you think this is a major flaw (like myself) please upvote the comment I left, we should get this fixed.

isomorphic-querystring

Aaron Reisman — Wed, 29 Jan 2020 18:08:26 +0000

Hi guys,

I'd like to share with you a NPM package called isomorphic-querystring.

it matches the same API as the querystring module in node's standard library. but if you're in the browser it uses 2 small functions to match the exact same API.

if you use SSR in JavaScript this package might be helpful to you.

please take a look, and star it if you don't mind :)

https://github.com/lifeiscontent/isomorphic-querystring