Molecule

What is a Molecule?

Molecules are functional UI groups composed of multiple atoms working together for a single purpose—like a search bar (input + button + icon) or form field (label + input + error). They're reusable interface patterns.

Key Principles

1. Composition Over Creation: Build molecules by composing existing atoms, don't recreate atom functionality inside molecules.

2. Single Cohesive Purpose: A molecule does one thing (search, form field, card header)—if it does multiple distinct things, it's probably an organism.

3. Props Passthrough: Molecules receive data and pass relevant props to child atoms. They orchestrate, not originate.

Best Practices

✅ DO:

• Import and compose atoms from your atom library
• Keep molecules under 100 lines of code
• Handle layout/spacing between atoms
• Communicate via callbacks (onSearch, onSubmit, onChange)
• Maintain consistent atom usage across similar molecules

❌ DON'T:

• Connect to global state or stores
• Fetch data—molecules are presentational
• Include complex business logic
• Hardcode atom variations—accept as props
• Nest molecules more than one level deep

Code Patterns

Recommended

// SearchBar.jsx - Molecule composing atoms
import Input from '../atoms/Input';
import Button from '../atoms/Button';
import Icon from '../atoms/Icon';

const SearchBar = ({ value, onChange, onSearch, placeholder }) => {
  const handleKeyPress = (e) => {
    if (e.key === 'Enter') onSearch(value);
  };

  return (
    <div className="search-bar">
      <Icon name="search" />
      <Input
        value={value}
        onChange={onChange}
        onKeyPress={handleKeyPress}
        placeholder={placeholder}
      />
      <Button label="Search" onClick={() => onSearch(value)} />
    </div>
  );
};

Avoid

// ❌ WRONG - Molecule connected to store
const SearchBar = () => {
  const dispatch = useDispatch();
  const query = useSelector(state => state.search.query);
  // Molecules shouldn't connect to store!
};

// ✅ CORRECT - Receives data via props
const SearchBar = ({ query, onQueryChange, onSearch }) => (
  // Pure presentational component
);

Related Terminologies

• Atom (UI) - Building blocks molecules are composed of
• Organism (UI) - Larger components that compose molecules
• Component (UI) - Generic term; molecules are presentational components
• Events (UI) - How molecules communicate user interactions

Quality Gates

• Composed of existing atoms (not recreating)
• Single cohesive purpose
• No state management connections
• No data fetching
• Handles layout between child atoms
• Uses callbacks for communication

Source: /docs/ui/molecule.md