Learning Objectives

Build production-ready UI components
Component composition patterns
Accessibility best practices
Creating a consistent design system

1. Component Library Structure

Organizing your components into a clear directory structure makes them easier to find, maintain, and import. The following structure separates UI primitives, layout components, and form-specific components into distinct folders.

components/
├── ui/
│   ├── Button.tsx
│   ├── Input.tsx
│   ├── Select.tsx
│   ├── Card.tsx
│   ├── Badge.tsx
│   ├── Avatar.tsx
│   ├── Modal.tsx
│   ├── Spinner.tsx
│   └── index.ts          # Export all
├── layout/
│   ├── Header.tsx
│   ├── Sidebar.tsx
│   ├── Footer.tsx
│   └── Container.tsx
└── forms/
    ├── FormField.tsx
    ├── PhoneInput.tsx
    └── AmountInput.tsx

2. Button Component

The Button component is one of the most frequently used UI elements in any application. This implementation uses forwardRef to properly handle ref forwarding, which is essential for integrating with form libraries and managing focus programmatically.

// components/ui/Button.tsx
import { forwardRef } from "react";
import { cn } from "@/lib/utils";
import Spinner from "./Spinner";

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "primary" | "secondary" | "outline" | "ghost" | "danger";
  size?: "sm" | "md" | "lg";
  loading?: boolean;
  leftIcon?: React.ReactNode;
  rightIcon?: React.ReactNode;
}

const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  (
    {
      children,
      variant = "primary",
      size = "md",
      loading = false,
      disabled,
      leftIcon,
      rightIcon,
      className,
      ...props
    },
    ref
  ) => {
    const variants = {
      primary: "bg-primary text-white hover:bg-primary-dark",
      secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200",
      outline:
        "border-2 border-primary text-primary hover:bg-primary hover:text-white",
      ghost: "text-gray-600 hover:bg-gray-100",
      danger: "bg-danger text-white hover:bg-red-600",
    };

    const sizes = {
      sm: "px-3 py-1.5 text-sm",
      md: "px-4 py-2.5",
      lg: "px-6 py-3 text-lg",
    };

    return (
      <button
        ref={ref}
        disabled={disabled || loading}
        className={cn(
          "inline-flex items-center justify-center gap-2 font-medium rounded-lg",
          "transition-all duration-200 active:scale-[0.98]",
          "disabled:opacity-50 disabled:cursor-not-allowed disabled:active:scale-100",
          variants[variant],
          sizes[size],
          className
        )}
        {...props}
      >
        {loading ? (
          <Spinner size="sm" />
        ) : leftIcon ? (
          <span className="w-5 h-5">{leftIcon}</span>
        ) : null}
        {children}
        {rightIcon && !loading && <span className="w-5 h-5">{rightIcon}</span>}
      </button>
    );
  }
);

Button.displayName = "Button";
export default Button;

3. Input Component

The Input component handles text input with support for labels, icons, error messages, and hints. Using forwardRef ensures compatibility with form libraries like React Hook Form that need direct access to the DOM element.

// components/ui/Input.tsx
import { forwardRef } from "react";
import { cn } from "@/lib/utils";

interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
  label?: string;
  error?: string;
  hint?: string;
  leftIcon?: React.ReactNode;
  rightIcon?: React.ReactNode;
}

const Input = forwardRef<HTMLInputElement, InputProps>(
  (
    { label, error, hint, leftIcon, rightIcon, className, id, ...props },
    ref
  ) => {
    const inputId = id || props.name;

    return (
      <div className="space-y-1.5">
        {label && (
          <label
            htmlFor={inputId}
            className="block text-sm font-medium text-gray-700"
          >
            {label}
            {props.required && <span className="text-danger ml-1">*</span>}
          </label>
        )}

        <div className="relative">
          {leftIcon && (
            <div className="absolute left-3 top-1/2 -translate-y-1/2 text-gray-400">
              {leftIcon}
            </div>
          )}

          <input
            ref={ref}
            id={inputId}
            className={cn(
              "w-full px-4 py-3 border rounded-lg",
              "focus:outline-none focus:ring-2 focus:ring-primary focus:border-transparent",
              "placeholder:text-gray-400",
              leftIcon && "pl-10",
              rightIcon && "pr-10",
              error ? "border-danger" : "border-gray-300",
              className
            )}
            {...props}
          />

          {rightIcon && (
            <div className="absolute right-3 top-1/2 -translate-y-1/2 text-gray-400">
              {rightIcon}
            </div>
          )}
        </div>

        {error && <p className="text-sm text-danger">{error}</p>}
        {hint && !error && <p className="text-sm text-gray-500">{hint}</p>}
      </div>
    );
  }
);

Input.displayName = "Input";
export default Input;

4. Select Component

The Select component provides a styled dropdown with support for labels, placeholder text, and error states. It renders a native select element for accessibility while applying custom styling through Tailwind classes.

// components/ui/Select.tsx
import { forwardRef } from "react";
import { cn } from "@/lib/utils";

interface Option {
  value: string;
  label: string;
  disabled?: boolean;
}

interface SelectProps extends React.SelectHTMLAttributes<HTMLSelectElement> {
  label?: string;
  error?: string;
  options: Option[];
  placeholder?: string;
}

const Select = forwardRef<HTMLSelectElement, SelectProps>(
  (
    {
      label,
      error,
      options,
      placeholder = "Select an option",
      className,
      id,
      ...props
    },
    ref
  ) => {
    const selectId = id || props.name;

    return (
      <div className="space-y-1.5">
        {label && (
          <label
            htmlFor={selectId}
            className="block text-sm font-medium text-gray-700"
          >
            {label}
            {props.required && <span className="text-danger ml-1">*</span>}
          </label>
        )}

        <select
          ref={ref}
          id={selectId}
          className={cn(
            "w-full px-4 py-3 border rounded-lg appearance-none",
            "bg-white bg-[url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' viewBox='0 0 24 24' stroke='%236b7280'%3E%3Cpath stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='M19 9l-7 7-7-7'/%3E%3C/svg%3E\")]",
            "bg-[length:1.5rem] bg-[right_0.5rem_center] bg-no-repeat",
            "focus:outline-none focus:ring-2 focus:ring-primary focus:border-transparent",
            error ? "border-danger" : "border-gray-300",
            className
          )}
          {...props}
        >
          <option value="" disabled>
            {placeholder}
          </option>
          {options.map((option) => (
            <option
              key={option.value}
              value={option.value}
              disabled={option.disabled}
            >
              {option.label}
            </option>
          ))}
        </select>

        {error && <p className="text-sm text-danger">{error}</p>}
      </div>
    );
  }
);

Select.displayName = "Select";
export default Select;

5. Card Component

The Card component provides a flexible container for grouping related content. It is composed of multiple sub-components (CardHeader, CardTitle, CardContent, CardFooter) that work together to create consistent card layouts throughout your application.

// components/ui/Card.tsx
import { cn } from "@/lib/utils";

interface CardProps {
  children: React.ReactNode;
  className?: string;
  hover?: boolean;
  padding?: "none" | "sm" | "md" | "lg";
}

export function Card({
  children,
  className,
  hover = false,
  padding = "md",
}: CardProps) {
  const paddings = {
    none: "",
    sm: "p-4",
    md: "p-6",
    lg: "p-8",
  };

  return (
    <div
      className={cn(
        "bg-white rounded-xl shadow-card",
        hover && "hover:shadow-elevated transition-shadow cursor-pointer",
        paddings[padding],
        className
      )}
    >
      {children}
    </div>
  );
}

export function CardHeader({
  children,
  className,
}: {
  children: React.ReactNode;
  className?: string;
}) {
  return (
    <div className={cn("pb-4 border-b border-gray-100", className)}>
      {children}
    </div>
  );
}

export function CardTitle({
  children,
  className,
}: {
  children: React.ReactNode;
  className?: string;
}) {
  return (
    <h3 className={cn("text-lg font-semibold text-gray-900", className)}>
      {children}
    </h3>
  );
}

export function CardContent({
  children,
  className,
}: {
  children: React.ReactNode;
  className?: string;
}) {
  return <div className={cn("pt-4", className)}>{children}</div>;
}

export function CardFooter({
  children,
  className,
}: {
  children: React.ReactNode;
  className?: string;
}) {
  return (
    <div className={cn("pt-4 border-t border-gray-100 mt-4", className)}>
      {children}
    </div>
  );
}

6. Badge Component

Badges are used to highlight status, categories, or counts. This implementation includes a default Badge component and a specialized StatusBadge component that maps common status strings to their appropriate visual variants.

// components/ui/Badge.tsx
import { cn } from "@/lib/utils";

interface BadgeProps {
  children: React.ReactNode;
  variant?: "default" | "success" | "warning" | "danger" | "info";
  size?: "sm" | "md";
}

export default function Badge({
  children,
  variant = "default",
  size = "sm",
}: BadgeProps) {
  const variants = {
    default: "bg-gray-100 text-gray-700",
    success: "bg-green-100 text-green-700",
    warning: "bg-yellow-100 text-yellow-700",
    danger: "bg-red-100 text-red-700",
    info: "bg-blue-100 text-blue-700",
  };

  const sizes = {
    sm: "px-2 py-0.5 text-xs",
    md: "px-2.5 py-1 text-sm",
  };

  return (
    <span
      className={cn(
        "inline-flex items-center font-medium rounded-full",
        variants[variant],
        sizes[size]
      )}
    >
      {children}
    </span>
  );
}

// Status badge for transactions
// This specialized component automatically maps transaction status strings to the appropriate badge variant, making it easy to display consistent status indicators throughout the application.
export function StatusBadge({ status }: { status: string }) {
  const statusVariants: Record<string, "success" | "warning" | "danger"> = {
    completed: "success",
    pending: "warning",
    processing: "info",
    failed: "danger",
  };

  return (
    <Badge variant={statusVariants[status] || "default"}>
      {status.charAt(0).toUpperCase() + status.slice(1)}
    </Badge>
  );
}

7. Modal Component

The Modal component creates an accessible dialog overlay using React portals. It handles keyboard events (Escape to close), prevents body scrolling when open, and closes when clicking the backdrop. The 'use client' directive is required since it uses React hooks and DOM APIs.

// components/ui/Modal.tsx
"use client";

import { useEffect, useRef } from "react";
import { createPortal } from "react-dom";
import { cn } from "@/lib/utils";

interface ModalProps {
  isOpen: boolean;
  onClose: () => void;
  title?: string;
  children: React.ReactNode;
  size?: "sm" | "md" | "lg" | "xl";
}

export default function Modal({
  isOpen,
  onClose,
  title,
  children,
  size = "md",
}: ModalProps) {
  const overlayRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const handleEscape = (e: KeyboardEvent) => {
      if (e.key === "Escape") onClose();
    };

    if (isOpen) {
      document.addEventListener("keydown", handleEscape);
      document.body.style.overflow = "hidden";
    }

    return () => {
      document.removeEventListener("keydown", handleEscape);
      document.body.style.overflow = "";
    };
  }, [isOpen, onClose]);

  if (!isOpen) return null;

  const sizes = {
    sm: "max-w-sm",
    md: "max-w-md",
    lg: "max-w-lg",
    xl: "max-w-xl",
  };

  return createPortal(
    <div
      ref={overlayRef}
      onClick={(e) => e.target === overlayRef.current && onClose()}
      className="fixed inset-0 z-50 flex items-center justify-center p-4 bg-black/50"
    >
      <div
        className={cn(
          "w-full bg-white rounded-xl shadow-xl",
          "animate-in fade-in zoom-in-95 duration-200",
          sizes[size]
        )}
      >
        {title && (
          <div className="flex items-center justify-between p-6 border-b">
            <h2 className="text-lg font-semibold">{title}</h2>
            <button
              onClick={onClose}
              className="p-1 rounded-lg hover:bg-gray-100 transition-colors"
            >
              <svg
                className="w-5 h-5"
                fill="none"
                stroke="currentColor"
                viewBox="0 0 24 24"
              >
                <path
                  strokeLinecap="round"
                  strokeLinejoin="round"
                  strokeWidth={2}
                  d="M6 18L18 6M6 6l12 12"
                />
              </svg>
            </button>
          </div>
        )}
        <div className="p-6">{children}</div>
      </div>
    </div>,
    document.body
  );
}

8. Spinner Component

The Spinner component provides a visual loading indicator using an SVG animation. It supports multiple sizes and inherits its color from the parent element's text color, making it versatile for different contexts.

// components/ui/Spinner.tsx
import { cn } from "@/lib/utils";

interface SpinnerProps {
  size?: "sm" | "md" | "lg";
  className?: string;
}

export default function Spinner({ size = "md", className }: SpinnerProps) {
  const sizes = {
    sm: "w-4 h-4",
    md: "w-6 h-6",
    lg: "w-8 h-8",
  };

  return (
    <svg
      className={cn("animate-spin text-current", sizes[size], className)}
      xmlns="http://www.w3.org/2000/svg"
      fill="none"
      viewBox="0 0 24 24"
    >
      <circle
        className="opacity-25"
        cx="12"
        cy="12"
        r="10"
        stroke="currentColor"
        strokeWidth="4"
      />
      <path
        className="opacity-75"
        fill="currentColor"
        d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
      />
    </svg>
  );
}

9. Network Selector Component

The Network Selector is a domain-specific component for selecting mobile network providers. It displays network options as a grid of clickable cards, each with the network's distinctive color. This pattern is common in bill payment applications for airtime and data purchases.

// components/forms/NetworkSelector.tsx
"use client";

import { cn } from "@/lib/utils";

interface Network {
  id: string;
  name: string;
  color: string;
}

const networks: Network[] = [
  { id: "mtn", name: "MTN", color: "bg-mtn" },
  { id: "airtel", name: "Airtel", color: "bg-airtel" },
  { id: "glo", name: "Glo", color: "bg-glo" },
  { id: "9mobile", name: "9Mobile", color: "bg-9mobile" },
];

interface NetworkSelectorProps {
  value: string;
  onChange: (value: string) => void;
  error?: string;
}

export default function NetworkSelector({
  value,
  onChange,
  error,
}: NetworkSelectorProps) {
  return (
    <div className="space-y-2">
      <label className="block text-sm font-medium text-gray-700">
        Select Network
      </label>
      <div className="grid grid-cols-4 gap-3">
        {networks.map((network) => (
          <button
            key={network.id}
            type="button"
            onClick={() => onChange(network.id)}
            className={cn(
              "flex flex-col items-center p-4 rounded-lg border-2 transition-all",
              value === network.id
                ? "border-primary bg-primary/5"
                : "border-gray-200 hover:border-gray-300"
            )}
          >
            <div className={cn("w-12 h-12 rounded-full", network.color)} />
            <span className="mt-2 text-sm font-medium">{network.name}</span>
          </button>
        ))}
      </div>
      {error && <p className="text-sm text-danger">{error}</p>}
    </div>
  );
}

10. Export All Components

Creating a barrel export file (index.ts) allows you to import multiple components from a single path. This simplifies imports throughout your application and makes it easier to manage your component library.

// components/ui/index.ts
export { default as Button } from "./Button";
export { default as Input } from "./Input";
export { default as Select } from "./Select";
export { Card, CardHeader, CardTitle, CardContent, CardFooter } from "./Card";
export { default as Badge, StatusBadge } from "./Badge";
export { default as Modal } from "./Modal";
export { default as Spinner } from "./Spinner";

// Usage
import { Button, Input, Card, Badge } from "@/components/ui";

Next Lesson: Dashboard Layout & Navigation