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 overviewatomic-design-atoms- Creating atomic componentsatomic-design-organisms- Building complex organisms