Controlled vs uncontrolled components
Every interactive Framer component eventually faces the same question:
who owns the state — the component itself or Framer?
That is the difference between a controlled and an uncontrolled component. Understanding this makes your components predictable, reusable, and compatible with data bindings.
What it means
A controlled component gets its value from props. The parent (Framer or CMS data) decides what the value is.
An uncontrolled component manages its own internal state. It decides what to do when a user interacts with it.
In Framer, this distinction matters because users can connect properties like activeIndex
, isOpen
, or value
to external data.
If your component does not respect controlled mode, it can get out of sync or ignore data bindings entirely.
Example
This example shows a simple accordion item that works in both modes.
When isOpen
is not connected, the component toggles itself and stores state internally.
When a designer binds isOpen
to a variable, it becomes controlled and expects the parent to manage its state through onChange
.
Why it matters
Controlled mode allows Framer bindings, CMS data, or external logic to drive your component’s behavior.
Uncontrolled mode keeps it simple when used as a standalone component.
Handling both makes your components feel professional and flexible.
Pro tip
Use a consistent pattern to detect control:
This single check prevents desyncs, double updates, and unpredictable behavior.
Your component should never fight its props — it should cooperate with them.