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';

/* molecules/FormField/FormField.module.css */ .field { display: flex; flex-direction: column; gap: 6px; }

.helpText { margin-top: 2px; }

.error { margin-top: 2px; display: flex; align-items: center; gap: 4px; }

SearchForm Molecule Example

// molecules/SearchForm/SearchForm.tsx import React, { useState, useCallback } from 'react'; import { Input } from '@/components/atoms/Input'; import { Button } from '@/components/atoms/Button'; import { Icon } from '@/components/atoms/Icon'; import styles from './SearchForm.module.css';

export interface SearchFormProps { /** Placeholder text / placeholder?: string; /* Initial search value / defaultValue?: string; /* Submit handler / onSubmit: (query: string) => void; /* Change handler for live search / onChange?: (query: string) => void; /* Loading state / isLoading?: boolean; /* Size variant / size?: 'sm' | 'md' | 'lg'; /* Show clear button */ clearable?: boolean; }

export const SearchForm: React.FC<SearchFormProps> = ({ placeholder = 'Search...', defaultValue = '', onSubmit, onChange, isLoading = false, size = 'md', clearable = true, }) => { const [query, setQuery] = useState(defaultValue);

const handleChange = useCallback( (e: React.ChangeEvent<HTMLInputElement>) => { const value = e.target.value; setQuery(value); onChange?.(value); }, [onChange] );

const handleSubmit = useCallback( (e: React.FormEvent) => { e.preventDefault(); onSubmit(query.trim()); }, [onSubmit, query] );

const handleClear = useCallback(() => { setQuery(''); onChange?.(''); }, [onChange]);

return ( <form className={styles.form} onSubmit={handleSubmit} role="search"> <Input type="search" value={query} onChange={handleChange} placeholder={placeholder} size={size} leftAddon={<Icon name="search" size="sm" />} rightAddon={ clearable && query ? ( <button type="button" onClick={handleClear} className={styles.clearButton} aria-label="Clear search" > <Icon name="x" size="sm" /> </button> ) : undefined } aria-label="Search query" /> <Button type="submit" size={size} isLoading={isLoading}> Search </Button> </form> ); };

SearchForm.displayName = 'SearchForm';

/* molecules/SearchForm/SearchForm.module.css */ .form { display: flex; gap: 8px; align-items: stretch; }

.clearButton { display: flex; align-items: center; justify-content: center; background: transparent; border: none; cursor: pointer; padding: 4px; color: var(--color-neutral-500); transition: color 150ms; }

.clearButton:hover { color: var(--color-neutral-700); }

MediaObject Molecule Example

// molecules/MediaObject/MediaObject.tsx import React from 'react'; import { Avatar, type AvatarProps } from '@/components/atoms/Avatar'; import { Text, Heading } from '@/components/atoms/Typography'; import styles from './MediaObject.module.css';

export interface MediaObjectProps { /** Avatar image source / avatarSrc?: string; /* Avatar alt text / avatarAlt: string; /* Avatar initials fallback / avatarInitials?: string; /* Avatar size / avatarSize?: AvatarProps['size']; /* Primary text/title / title: React.ReactNode; /* Secondary text/subtitle / subtitle?: React.ReactNode; /* Additional metadata / meta?: React.ReactNode; /* Right-aligned action element / action?: React.ReactNode; /* Alignment of content / align?: 'top' | 'center' | 'bottom'; /* Additional class name */ className?: string; }

export const MediaObject: React.FC<MediaObjectProps> = ({ avatarSrc, avatarAlt, avatarInitials, avatarSize = 'md', title, subtitle, meta, action, align = 'center', className, }) => { const classNames = [styles.mediaObject, styles[align-${align}], className] .filter(Boolean) .join(' ');

return ( <div className={classNames}> <Avatar src={avatarSrc} alt={avatarAlt} initials={avatarInitials} size={avatarSize} />

  <div className={styles.content}>
    <div className={styles.title}>{title}</div>
    {subtitle && (
      <Text size="sm" color="muted" className={styles.subtitle}>
        {subtitle}
      </Text>
    )}
    {meta && (
      <Text size="xs" color="muted" className={styles.meta}>
        {meta}
      </Text>
    )}
  </div>

  {action && <div className={styles.action}>{action}</div>}
</div>

); };

MediaObject.displayName = 'MediaObject';

NavItem Molecule Example

// molecules/NavItem/NavItem.tsx import React from 'react'; import { Icon } from '@/components/atoms/Icon'; import { Badge } from '@/components/atoms/Badge'; import styles from './NavItem.module.css';

export interface NavItemProps { /** Navigation icon / icon?: string; /* Item label / label: string; /* Link destination / href: string; /* Active state / isActive?: boolean; /* Badge count / badge?: number; /* Disabled state / disabled?: boolean; /* Click handler */ onClick?: (e: React.MouseEvent) => void; }

export const NavItem: React.FC<NavItemProps> = ({ icon, label, href, isActive = false, badge, disabled = false, onClick, }) => { const classNames = [ styles.navItem, isActive && styles.active, disabled && styles.disabled, ] .filter(Boolean) .join(' ');

const handleClick = (e: React.MouseEvent) => { if (disabled) { e.preventDefault(); return; } onClick?.(e); };

return ( <a href={href} className={classNames} onClick={handleClick} aria-current={isActive ? 'page' : undefined} aria-disabled={disabled} > {icon && <Icon name={icon} size="sm" className={styles.icon} />} <span className={styles.label}>{label}</span> {badge !== undefined && badge > 0 && ( <Badge variant="primary" size="sm" className={styles.badge}> {badge > 99 ? '99+' : badge} </Badge> )} </a> ); };

NavItem.displayName = 'NavItem';

CardHeader Molecule Example

// molecules/CardHeader/CardHeader.tsx import React from 'react'; import { Heading, Text } from '@/components/atoms/Typography'; import { Icon } from '@/components/atoms/Icon'; import { Button } from '@/components/atoms/Button'; import styles from './CardHeader.module.css';

export interface CardHeaderProps { /** Card title / title: string; /* Optional subtitle / subtitle?: string; /* Title icon / icon?: string; /* Action button label / actionLabel?: string; /* Action button click handler / onAction?: () => void; /* Additional class name */ className?: string; }

export const CardHeader: React.FC<CardHeaderProps> = ({ title, subtitle, icon, actionLabel, onAction, className, }) => { return ( <div className={${styles.header} ${className || ''}}> <div className={styles.left}> {icon && <Icon name={icon} size="md" className={styles.icon} />} <div className={styles.titles}> <Heading level={3} className={styles.title}> {title} </Heading> {subtitle && ( <Text size="sm" color="muted"> {subtitle} </Text> )} </div> </div>

  {actionLabel && onAction && (
    <Button variant="tertiary" size="sm" onClick={onAction}>
      {actionLabel}
    </Button>
  )}
</div>

); };

CardHeader.displayName = 'CardHeader';

ListItem Molecule Example

// molecules/ListItem/ListItem.tsx import React from 'react'; import { Checkbox } from '@/components/atoms/Checkbox'; import { Text } from '@/components/atoms/Typography'; import { Icon } from '@/components/atoms/Icon'; import styles from './ListItem.module.css';

export interface ListItemProps { /** Item ID for selection / id: string; /* Primary content / primary: React.ReactNode; /* Secondary content / secondary?: React.ReactNode; /* Left icon / icon?: string; /* Whether item is selectable / selectable?: boolean; /* Selection state / selected?: boolean; /* Selection change handler / onSelect?: (id: string, selected: boolean) => void; /* Right-aligned action buttons / actions?: React.ReactNode; /* Click handler */ onClick?: () => void; }

export const ListItem: React.FC<ListItemProps> = ({ id, primary, secondary, icon, selectable = false, selected = false, onSelect, actions, onClick, }) => { const classNames = [ styles.listItem, onClick && styles.clickable, selected && styles.selected, ] .filter(Boolean) .join(' ');

const handleCheckboxChange = (e: React.ChangeEvent<HTMLInputElement>) => { onSelect?.(id, e.target.checked); };

return ( <div className={classNames} onClick={onClick} role={onClick ? 'button' : undefined}> {selectable && ( <Checkbox checked={selected} onChange={handleCheckboxChange} aria-label={Select ${primary}} onClick={(e) => e.stopPropagation()} /> )}

  {icon && <Icon name={icon} size="md" className={styles.icon} />}

  <div className={styles.content}>
    <div className={styles.primary}>{primary}</div>
    {secondary && (
      <Text size="sm" color="muted" className={styles.secondary}>
        {secondary}
      </Text>
    )}
  </div>

  {actions && (
    <div className={styles.actions} onClick={(e) => e.stopPropagation()}>
      {actions}
    </div>
  )}
</div>

); };

ListItem.displayName = 'ListItem';

ButtonGroup Molecule Example

// molecules/ButtonGroup/ButtonGroup.tsx import React from 'react'; import { Button, type ButtonProps } from '@/components/atoms/Button'; import styles from './ButtonGroup.module.css';

export interface ButtonGroupItem { id: string; label: string; icon?: string; disabled?: boolean; }

export interface ButtonGroupProps { /** Button items / items: ButtonGroupItem[]; /* Selected item ID(s) / value?: string | string[]; /* Selection change handler / onChange?: (value: string | string[]) => void; /* Allow multiple selection / multiple?: boolean; /* Size variant / size?: ButtonProps['size']; /* Disabled state */ disabled?: boolean; }

export const ButtonGroup: React.FC<ButtonGroupProps> = ({ items, value = [], onChange, multiple = false, size = 'md', disabled = false, }) => { const selectedIds = Array.isArray(value) ? value : [value].filter(Boolean);

const handleClick = (itemId: string) => { if (!onChange) return;

if (multiple) {
  const newValue = selectedIds.includes(itemId)
    ? selectedIds.filter((id) => id !== itemId)
    : [...selectedIds, itemId];
  onChange(newValue);
} else {
  onChange(itemId);
}

};

return ( <div className={styles.group} role="group"> {items.map((item) => { const isSelected = selectedIds.includes(item.id);

    return (
      <Button
        key={item.id}
        variant={isSelected ? 'primary' : 'secondary'}
        size={size}
        disabled={disabled || item.disabled}
        onClick={() => handleClick(item.id)}
        aria-pressed={isSelected}
        className={styles.button}
      >
        {item.label}
      </Button>
    );
  })}
</div>

); };

ButtonGroup.displayName = 'ButtonGroup';

Stat Molecule Example

// molecules/Stat/Stat.tsx import React from 'react'; import { Text, Heading } from '@/components/atoms/Typography'; import { Icon } from '@/components/atoms/Icon'; import styles from './Stat.module.css';

export type TrendDirection = 'up' | 'down' | 'neutral';

export interface StatProps { /** Stat label / label: string; /* Stat value / value: string | number; /* Previous value for comparison / previousValue?: string | number; /* Trend direction / trend?: TrendDirection; /* Trend percentage / trendValue?: string; /* Stat icon / icon?: string; /* Help text */ helpText?: string; }

export const Stat: React.FC<StatProps> = ({ label, value, trend, trendValue, icon, helpText, }) => { const getTrendColor = (direction?: TrendDirection) => { switch (direction) { case 'up': return 'success'; case 'down': return 'danger'; default: return 'muted'; } };

const getTrendIcon = (direction?: TrendDirection) => { switch (direction) { case 'up': return 'trending-up'; case 'down': return 'trending-down'; default: return 'minus'; } };

return ( <div className={styles.stat}> <div className={styles.header}> {icon && <Icon name={icon} size="sm" className={styles.icon} />} <Text size="sm" color="muted"> {label} </Text> </div>

  <div className={styles.value}>
    <Heading level={2}>{value}</Heading>
  </div>

  {(trend || trendValue) && (
    <div className={styles.trend}>
      {trend && (
        <Icon
          name={getTrendIcon(trend)}
          size="xs"
          color={`var(--color-${getTrendColor(trend)}-500)`}
        />
      )}
      {trendValue && (
        <Text size="sm" color={getTrendColor(trend)}>
          {trendValue}
        </Text>
      )}
    </div>
  )}

  {helpText && (
    <Text size="xs" color="muted" className={styles.helpText}>
      {helpText}
    </Text>
  )}
</div>

); };

Stat.displayName = 'Stat';

Best Practices

1. Keep Molecules Focused

// GOOD: Single, clear purpose const SearchForm = () => ( <form> <Input placeholder="Search..." /> <Button>Search</Button> </form> );

// BAD: Doing too much const SearchWithFiltersAndResults = () => ( <div> <Input /> <Button>Search</Button> <FilterDropdown /> {/* Should be separate molecule /} <ResultsList /> {/ Should be organism /} <Pagination /> {/ Should be separate molecule */} </div> );

2. Only Import from Atoms

// GOOD: Only uses atoms import { Button } from '@/components/atoms/Button'; import { Input } from '@/components/atoms/Input'; import { Icon } from '@/components/atoms/Icon';

// BAD: Importing from other molecules import { FormField } from '@/components/molecules/FormField'; // Wrong level! import { Button } from '@/components/atoms/Button';

3. Compose Props Carefully

// GOOD: Clear prop forwarding interface SearchFormProps { onSubmit: (query: string) => void; inputProps?: Partial<InputProps>; buttonProps?: Partial<ButtonProps>; }

// BAD: Confusing prop naming interface SearchFormProps { inputPlaceholder?: string; inputDisabled?: boolean; inputSize?: string; buttonVariant?: string; buttonDisabled?: boolean; // ... endless prop forwarding }

4. Manage Internal State Minimally

// GOOD: Minimal UI state const SearchForm = ({ onSubmit }) => { const [query, setQuery] = useState('');

return ( <form onSubmit={() => onSubmit(query)}> <Input value={query} onChange={(e) => setQuery(e.target.value)} /> <Button type="submit">Search</Button> </form> ); };

// BAD: Too much internal state const SearchForm = () => { const [query, setQuery] = useState(''); const [results, setResults] = useState([]); // Should be in parent const [isLoading, setIsLoading] = useState(false); const [error, setError] = useState(null);

useEffect(() => { fetchResults(query).then(setResults); // Business logic in molecule! }, [query]); };

Anti-Patterns to Avoid

1. Molecules Containing Molecules

// BAD: Molecule importing another molecule // molecules/ComplexForm/ComplexForm.tsx import { FormField } from '../FormField'; // Wrong! import { SearchForm } from '../SearchForm'; // Wrong!

// GOOD: Keep at atom level, or promote to organism // organisms/ComplexForm/ComplexForm.tsx import { FormField } from '@/components/molecules/FormField'; import { SearchForm } from '@/components/molecules/SearchForm';

2. Business Logic in Molecules

// BAD: API calls in molecule const SearchForm = ({ apiEndpoint }) => { const handleSubmit = async (query) => { const results = await fetch(${apiEndpoint}?q=${query}); // Processing results here... }; };

// GOOD: Delegate to parent const SearchForm = ({ onSubmit }) => { const handleSubmit = (query) => { onSubmit(query); // Parent handles API logic }; };

3. Over-Abstraction

// BAD: Unnecessary molecule for single atom const IconWrapper = ({ icon }) => <Icon name={icon} />;

// GOOD: Just use the atom directly <Icon name="search" />

When to Use This Skill

• Combining atoms for specific functionality

• Creating reusable form components

• Building navigation elements

• Creating card and list components

• Establishing patterns for common UI combinations

Related Skills

• atomic-design-fundamentals

• Core methodology overview

• atomic-design-atoms

• Creating atomic components

• atomic-design-organisms

• Building complex organisms