Improve LayoutGroup Documentation (Clarify vs. motion.div layout)

[anishwij]

Is your feature request related to a problem? Please describe.

Currently, both motion.div with the layout prop and LayoutGroup use the word “layout,” but they perform very different tasks. This can confuse developers who assume LayoutGroup is merely a wrapper for local layout animations. In reality, LayoutGroup provides context that enables shared or coordinated layout animations among multiple components.

Naming: “LayoutGroup” can be interpreted as analogous to motion.div layout, but it actually serves a “provider” role.

Documentation: The official docs don’t provide an immediately clear, side-by-side comparison explaining when you’d use a single motion.div layout versus when you’d need a LayoutGroup.

Describe the solution you'd like

1. Rename or Add Clarifying Copy. Consider renaming LayoutGroup (e.g., LayoutProvider) in a future major release.
   At the very least, add a prominent note or section at the top of the docs to clarify that it is used for cross-component layout coordination, not local layout animations.
   Side-by-Side Examples

2. Side-by-Side Examples Show how a single motion.div layout animates layout changes in a single component or DOM subtree.
   Demonstrate how wrapping multiple components in LayoutGroup allows them to coordinate layout changes—like in an accordion, shared layout transitions, etc.

// Local layout animations
const Card = () => (
  <motion.div layout>
    <Content />
  </motion.div>
)

// Cross-component coordination
const App = () => (
  <LayoutGroup>
    <Nav>
      <MenuItem />
    </Nav>
    <Main>
      <Content />
    </Main>
  </LayoutGroup>
)

Describe alternatives you've considered
...

Additional context

I’ve spent significant time experimenting to figure out how best to coordinate layouts across components. After understanding it, I realized the official docs provide minimal explanation for exactly when or why to reach for LayoutGroup vs. motion.div layout. Having this spelled out in the docs will spare other devs from trial-and-error.