Building Modular UI Components with React

Table of Contents

1. Understanding Modularity in React
   • What Are Modular UI Components?
   • Benefits of Modular Components
2. Core Principles of Modular Component Design
   • Single Responsibility Principle
   • Reusability
   • Composability
   • Isolation
   • Declarative Design
3. Step-by-Step Guide to Building Modular Components
   • Setting Up the Project
   • Building a Basic Component: The Button
   • Adding Configurability with Props
   • Adding Interactivity with State
   • Composing Components: The Card
   • Styling Modular Components
4. Advanced Techniques for Modular Components
   • Custom Hooks for Logic Reuse
   • Compound Components
   • Render Props (Legacy but Useful)
   • Type Safety with TypeScript
5. Best Practices for Modular Component Development
   • Naming Conventions
   • Folder Structure
   • Prop Validation
   • Avoiding Prop Drilling
   • Documentation with Storybook
6. Testing Modular Components
   • Unit Testing with Jest and React Testing Library
   • Testing Props and Interactions
   • Integration Testing
7. Conclusion
8. References

1. Understanding Modularity in React

What Are Modular UI Components?

Modular UI components are self-contained, reusable pieces of code that encapsulate a specific UI functionality (e.g., a button, form input, or navigation bar). They are designed to be independent, meaning they can be developed, tested, and maintained in isolation without relying on the entire application.

In React, components are the fundamental building blocks, and modularity takes this a step further by enforcing strict boundaries between components. A modular component should:

• Focus on one task (e.g., a Button shouldn’t handle form validation).
• Expose a clear API (via props) for customization.
• Avoid tight coupling with other components.

Benefits of Modular Components

• Reusability: Components like Button or Card can be used across multiple parts of an application (e.g., a checkout page, product listing, or user profile).
• Maintainability: Isolated components are easier to debug and update. Changing a Button’s styling won’t break unrelated features.
• Scalability: As applications grow, modular components reduce code duplication and simplify onboarding for new developers.
• Collaboration: Teams can work on separate components (e.g., one team builds FormInput, another builds Modal) without conflicts.

2. Core Principles of Modular Component Design

To build truly modular components, follow these principles:

Single Responsibility Principle (SRP)

A component should do one thing and do it well. For example:

• A Button component handles rendering a clickable button and nothing else.
• A Card component displays a container with a title, image, and description—but delegates button functionality to a Button component.

Example of SRP Violation: A UserProfile component that fetches user data, renders a profile card, and handles form submission for editing. Instead, split this into UserProfile (renders), useUserData (custom hook for data fetching), and ProfileEditForm (handles submission).

Reusability

Design components to work in multiple contexts. Avoid hardcoding values (e.g., “Submit” text in a button). Instead, use props to make components configurable.

Example: A reusable Button might accept label, variant (primary, secondary), and onClick props to adapt to different use cases.

Composability

Modular components should work together to build complex UIs. React’s children prop and component composition enable this. For example, a Card component can wrap a Button and Avatar component to create a user card.

Example:

// Card component accepting children
const Card = ({ children }) => (
  <div className="card">{children}</div>
);

// Usage: Composing Card with Button and Avatar
<Card>
  <Avatar src="/user.jpg" />
  <h3>John Doe</h3>
  <Button label="Follow" />
</Card>

Isolation

Components should not depend on external state or styles unless explicitly passed via props. Avoid global variables or side effects (e.g., modifying the DOM directly) inside components.

Example: A Dropdown component should manage its own isOpen state internally or accept an isOpen prop for parent control—not rely on a global window.dropdownState.

Declarative Design

React encourages declarative code: describe what the UI should look like, not how to render it. Modular components should use props to declare their behavior (e.g., disabled={true}) instead of imperative logic (e.g., if (isDisabled) { ... }).

3. Step-by-Step Guide to Building Modular Components

Let’s build modular components from scratch, starting with a simple Button and progressing to a composed Card.

Setting Up the Project

First, create a new React project using Vite (faster than Create React App):

npm create vite@latest modular-components -- --template react
cd modular-components
npm install
npm run dev

Step 1: Build a Basic Component: The Button

Start with a reusable Button component. It will accept props for label, variant, and onClick.

File: src/components/Button/Button.jsx

const Button = ({ label, variant = "primary", onClick }) => {
  // Define styles based on variant
  const baseStyles = "px-4 py-2 rounded font-medium";
  const variantStyles = {
    primary: "bg-blue-600 text-white hover:bg-blue-700",
    secondary: "bg-gray-200 text-gray-800 hover:bg-gray-300",
  }[variant];

  return (
    <button 
      className={`${baseStyles} ${variantStyles}`} 
      onClick={onClick}
    >
      {label}
    </button>
  );
};

export default Button;

Usage:

// Primary button
<Button label="Submit" variant="primary" onClick={() => alert("Submitted!")} />

// Secondary button
<Button label="Cancel" variant="secondary" />

Step 2: Adding Configurability with Props

Enhance the Button with more props for flexibility:

• size: “sm”, “md”, “lg” (controls padding/font size).
• disabled: Boolean to disable the button.

Updated Button:

const Button = ({ 
  label, 
  variant = "primary", 
  size = "md", 
  disabled = false, 
  onClick 
}) => {
  const baseStyles = "rounded font-medium";
  const variantStyles = {
    primary: "bg-blue-600 text-white hover:bg-blue-700",
    secondary: "bg-gray-200 text-gray-800 hover:bg-gray-300",
  }[variant];
  const sizeStyles = {
    sm: "px-2 py-1 text-sm",
    md: "px-4 py-2 text-base",
    lg: "px-6 py-3 text-lg",
  }[size];

  return (
    <button 
      className={`${baseStyles} ${variantStyles} ${sizeStyles}`} 
      disabled={disabled}
      onClick={onClick}
    >
      {label}
    </button>
  );
};

Now the Button adapts to size and disabled states:

<Button label="Small" size="sm" />
<Button label="Disabled" disabled />

Step 3: Adding Interactivity with State

Some components need internal state. For example, a ToggleButton that switches between “On” and “Off”. Use React’s useState hook for this.

ToggleButton Component:

import { useState } from "react";

const ToggleButton = () => {
  const [isOn, setIsOn] = useState(false);

  return (
    <Button
      label={isOn ? "On" : "Off"}
      variant={isOn ? "primary" : "secondary"}
      onClick={() => setIsOn(!isOn)}
    />
  );
};

Step 4: Composing Components: The Card

Build a Card component that composes smaller components (e.g., Button, Image). Use the children prop to make it flexible.

Card Component:

const Card = ({ children, className = "" }) => (
  <div className={`p-4 border rounded-lg shadow-sm ${className}`}>
    {children}
  </div>
);

// Usage: Card with title, image, and Button
<Card className="max-w-sm">
  <img src="/product.jpg" alt="Product" className="w-full rounded" />
  <h2 className="text-xl font-bold mt-2">Wireless Headphones</h2>
  <p className="text-gray-600 mt-1">Noise-cancelling, 20-hour battery</p>
  <Button label="Add to Cart" variant="primary" className="mt-3" />
</Card>

Step 5: Styling Modular Components

Styling is critical for modularity. Avoid global CSS (which causes conflicts). Use these approaches:

CSS Modules

Encapsulate styles to avoid leaks. Create Button.module.css and import styles scoped to the component:

/* Button.module.css */
.base {
  rounded: 4px;
  font-medium;
}
.primary {
  background: #3b82f6;
  color: white;
}

import styles from "./Button.module.css";

const Button = ({ variant }) => (
  <button className={`${styles.base} ${styles[variant]}`}>Submit</button>
);

Styled Components

Use the styled-components library for component-scoped styles with dynamic props:

import styled from "styled-components";

const StyledButton = styled.button`
  padding: ${(props) => props.size === "sm" ? "8px" : "16px"};
  background: ${(props) => props.variant === "primary" ? "blue" : "gray"};
`;

const Button = ({ label, variant, size }) => (
  <StyledButton variant={variant} size={size}>{label}</StyledButton>
);

Tailwind CSS

Utility-first CSS for rapid styling. Use className with Tailwind utilities:

const Button = ({ variant }) => (
  <button className={`px-4 py-2 rounded ${
    variant === "primary" ? "bg-blue-500 text-white" : "bg-gray-200"
  }`}>
    Submit
  </button>
);

4. Advanced Techniques for Modular Components

Custom Hooks for Logic Reuse

Extract reusable logic (e.g., form handling, state management) into custom hooks. For example, useToggle for components needing on/off state:

useToggle Hook:

// hooks/useToggle.js
export const useToggle = (initialState = false) => {
  const [state, setState] = useState(initialState);
  const toggle = () => setState(!state);
  return [state, toggle];
};

// Usage in ToggleButton
const ToggleButton = () => {
  const [isOn, toggle] = useToggle(false);
  return <Button onClick={toggle} label={isOn ? "On" : "Off"} />;
};

Compound Components

Build components that work together as a group (e.g., Tabs, Accordion). Use React context to share state between child components.

Example: Tabs Component

import { createContext, useContext, useState } from "react";

const TabsContext = createContext();

export const Tabs = ({ children, defaultValue }) => {
  const [activeKey, setActiveKey] = useState(defaultValue);
  return (
    <TabsContext.Provider value={{ activeKey, setActiveKey }}>
      <div className="tabs">{children}</div>
    </TabsContext.Provider>
  );
};

export const TabsList = ({ children }) => <div className="tabs-list">{children}</div>;

export const TabsTrigger = ({ children, value }) => {
  const { activeKey, setActiveKey } = useContext(TabsContext);
  return (
    <button 
      onClick={() => setActiveKey(value)}
      className={activeKey === value ? "active" : ""}
    >
      {children}
    </button>
  );
};

// Usage
<Tabs defaultValue="tab1">
  <TabsList>
    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
  </TabsList>
  <TabsContent value="tab1">Content 1</TabsContent>
  <TabsContent value="tab2">Content 2</TabsContent>
</Tabs>

TypeScript for Type Safety

Add type definitions to props to catch errors early. Define interfaces for component props:

Button with TypeScript:

interface ButtonProps {
  label: string;
  variant: "primary" | "secondary";
  size?: "sm" | "md" | "lg";
  onClick?: () => void;
}

const Button = ({ label, variant, size = "md", onClick }: ButtonProps) => (
  <button variant={variant} size={size} onClick={onClick}>
    {label}
  </button>
);

5. Best Practices for Modular Component Development

Naming Conventions

• Use PascalCase for component files and names (e.g., Button.jsx, UserCard.jsx).
• Suffix utility components (e.g., IconButton, LoadingSpinner).
• Name props descriptively: isOpen instead of open, onSubmit instead of submit.

Folder Structure

Organize components by feature or type. Example:

src/
  components/
    common/          # Reusable across app (Button, Card, Input)
      Button/
        Button.jsx
        Button.module.css
        Button.test.jsx
    features/        # Feature-specific (ProductCard, CheckoutForm)
      product/
        ProductCard.jsx
  hooks/             # Custom hooks (useToggle, useForm)
  utils/             # Helper functions

Prop Validation

Use PropTypes or TypeScript to validate props and document expected values:

PropTypes Example:

import PropTypes from "prop-types";

Button.propTypes = {
  label: PropTypes.string.isRequired,
  variant: PropTypes.oneOf(["primary", "secondary"]),
  onClick: PropTypes.func,
};

Avoiding Prop Drilling

Passing props through multiple levels (e.g., App → Parent → Child → Grandchild) leads to messy code. Use React Context or state management libraries (Redux, Zustand) for shared state.

Documentation with Storybook

Use Storybook to document components. Write “stories” to showcase variants (e.g., primary button, disabled button) and enable interactive testing:

// Button.stories.jsx
import Button from "./Button";

export default { component: Button, title: "Components/Button" };

export const Primary = () => <Button label="Submit" variant="primary" />;
export const Disabled = () => <Button label="Submit" disabled />;

6. Testing Modular Components

Modular components are easy to test in isolation. Use Jest and React Testing Library.

Unit Testing

Test component rendering, props, and interactions:

Example: Testing Button

import { render, screen, fireEvent } from "@testing-library/react";
import Button from "./Button";

test("renders label correctly", () => {
  render(<Button label="Submit" />);
  expect(screen.getByText("Submit")).toBeInTheDocument();
});

test("calls onClick when clicked", () => {
  const handleClick = jest.fn();
  render(<Button label="Click" onClick={handleClick} />);
  fireEvent.click(screen.getByText("Click"));
  expect(handleClick).toHaveBeenCalled();
});

Integration Testing

Test composed components (e.g., Card with Button):

test("Card renders Button and title", () => {
  render(
    <Card>
      <h2>Hello</h2>
      <Button label="Click" />
    </Card>
  );
  expect(screen.getByText("Hello")).toBeInTheDocument();
  expect(screen.getByText("Click")).toBeInTheDocument();
});

7. Conclusion

Modular UI components are the foundation of scalable, maintainable React applications. By following principles like single responsibility, reusability, and composability, you can build components that adapt to changing requirements and reduce technical debt.

Start small: build a reusable Button or Card, then layer in advanced techniques like compound components or custom hooks. Use tools like Storybook for documentation and Testing Library for confidence in your code.

With modular components, you’ll write cleaner code, collaborate more effectively, and ship features faster.

8. References

• React Official Docs: Components and Props
• Storybook Documentation
• React Testing Library
• Modular Components in React (Kent C. Dodds)
• TypeScript for React Components
• CSS Modules Documentation