atomic-design-molecules

Atomic Design: Molecules

Master the creation of molecule components - functional groups of atoms that work together as a unit. Molecules combine multiple atoms to create more complex, purposeful UI elements.

What Are Molecules?

Molecules are the first level of composition in Atomic Design. They are:

• Composed of atoms only: Never include other molecules
• Single purpose: Do one thing well
• Functional units: Atoms working together for a specific task
• Reusable: Used across different organisms and contexts
• Minimally stateful: May have limited internal state for UI concerns

Common Molecule Types

Form Molecules

• Form fields (label + input + error)
• Search forms (input + button)
• Toggle groups (label + toggle)
• Date pickers (input + calendar trigger)
• File uploaders (dropzone + button)

Navigation Molecules

• Nav items (icon + text + indicator)
• Breadcrumb items (link + separator)
• Pagination controls (buttons + page indicator)
• Tab items (icon + label)

Display Molecules

• Media objects (avatar + text)
• Card headers (title + subtitle + action)
• List items (checkbox + content + actions)
• Stat displays (label + value + trend)

Action Molecules

• Button groups (multiple buttons)
• Dropdown triggers (button + icon)
• Icon buttons (icon + tooltip)
• Action menus (button + menu items)

FormField Molecule Example

Complete Implementation

// molecules/FormField/FormField.tsx
import React from 'react';
import { Label } from '@/components/atoms/Label';
import { Input, type InputProps } from '@/components/atoms/Input';
import { Text } from '@/components/atoms/Typography';
import styles from './FormField.module.css';

export interface FormFieldProps extends InputProps {
  /** Field label */
  label: string;
  /** Unique field identifier */
  name: string;
  /** Help text below input */
  helpText?: string;
  /** Error message */
  error?: string;
  /** Required field indicator */
  required?: boolean;
}

export const FormField = React.forwardRef<HTMLInputElement, FormFieldProps>(
  (
    {
      label,
      name,
      helpText,
      error,
      required = false,
      id,
      className,
      ...inputProps
    },
    ref
  ) => {
    const fieldId = id || `field-${name}`;
    const helpTextId = helpText ? `${fieldId}-help` : undefined;
    const errorId = error ? `${fieldId}-error` : undefined;

    const describedBy = [helpTextId, errorId].filter(Boolean).join(' ') || undefined;

    return (
      <div className={`${styles.field} ${className || ''}`}>
        <Label htmlFor={fieldId} required={required} disabled={inputProps.disabled}>
          {label}
        </Label>

        <Input
          ref={ref}
          id={fieldId}
          name={name}
          hasError={!!error}
          aria-describedby={describedBy}
          aria-required={required}
          {...inputProps}
        />

        {helpText && !error && (
          <Text id={helpTextId} size="sm" color="muted" className={styles.helpText}>
            {helpText}
          </Text>
        )}

        {error && (
          <Text id={errorId} size="sm" color="danger" className={styles.error} role="alert">
            {error}
          </Text>
        )}
      </div>
    );
  }
);

FormField.displayName = 'FormField';