Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[📖] explain uncontrolled vs controlled components

Open
  • Is something wrong?
#6,336 5 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
Half a day
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
react, typescript
Domain
documentation, frontend

Research direction

Start with the proposed /guides/react-cheat-sheet location and review the supplied controlled and uncontrolled examples. Add a fake reusable-component implementation, improve the wording, and clarify the Qwik-versus-React API rationale only where supported. The work is done when the guide clearly explains the patterns and examples are consistent.

Written by the indexing model from the issue text.

Description

docs
Suggestion

Perhaps tbd in /guides/react-cheat-sheet

Uncontrolled vs controlled

In Qwik, the value prop by default behaves like the vanilla html value attribute. So the pattern is the following:

//uncontrolled -> behaves like vanilla html
<input type="checkbox" checked={true} />

//controlled (one way data-binding)
const acceptConditions = useSignal(false);
<input type="checkbox" checked={acceptConditions.value} onChange$={(_, el) => acceptConditions.value = el.checked } />

//controlled (two way data-binding = syntactic sugar to achieve above behavior)
const acceptConditions = useSignal(false);
<input type="checkbox" bind:checked={acceptConditions} />

React provides defaultValue, defaultOpen, defaultToggled, etc. props to enable "uncontrolled" inputs for when you want your inputs to work with vanilla html forms. This is because if you just set a value attribute like in vanilla html it will be interpreted as a controlled component by React and won't work. You have to also set an onChange event handler to express how to update the state the other way around.

The React pattern is the following:

//uncontrolled (this is different from native HTML)
<input type="checkbox" defaultChecked={true} />

//controlled (one way data-binding)
const [acceptConditions, setAcceptConditions] = useState(false);
<input type="checkbox" checked={acceptConditions} onChange$={(e) => setAcceptConditions(e.target.checked)} />

//controlled (two way data-binding)
There are no "two way data-binding" in React 🤪
Consistency recommendation for reusable components:

To keep your APIs consistent in Qwik Land, we recommend using the Qwik input patterns on your reusable components. For example:

//uncontrolled
<ComponentRoot open={true} />

//controlled (one way data-binding)
const isOpen = useSignal<boolean>(true);
<ComponentRoot open={isOpen.value} onChange${() => isOpen.value = !isOpen.value} />

//controlled (two way data-binding)
const isOpen = useSignal<boolean>(true);
<ComponentRoot bind:open={isOpen} />

TODO:

  • add an example implementation with a fake reusable component
  • Maybe explain why we can keep the API similar to native HTML in Qwik while React can't? Is it because of signals? I'm not sure..
  • Improve the wording and sentences structure
Dominant language
TypeScript
Stars
22.1k
Forks
1.4k
Avg merge
1d 17h
Merged PRs (30d)
98

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from QwikDev/qwik

All issues in QwikDev/qwik

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.