state — Claude Code rule: component state
state is a Claude Code rule for controlled and uncontrolled React component state. It applies while designing component APIs and state props.
Apache-2.0 ★ 141 updated 2026-11-17
.claude/rules/state.mdWhat state does
The state rule defines two ways for a React component to handle its value. In uncontrolled mode, the component owns the state; in controlled mode, a parent supplies the value and change handler. The pattern covers coordination with external data, form validation, and persistence.
Use useControllableState from @radix-ui/react-use-controllable-state to combine both modes. The rule maps common API pairs such as value with defaultValue, checked with defaultChecked, and open with defaultOpen, along with their change callbacks. The combined pattern requires @radix-ui/react-use-controllable-state.
What it helps with
- choose a controlled or uncontrolled state model for a component
- coordinate component state with a parent value
- support
valueanddefaultValuein one component API - standardize state props and change callbacks
Example prompts for the agent
- Design a Stepper component that supports controlled and uncontrolled state.
- Add
checked,defaultChecked, andonCheckedChangeto Toggle. - Refactor this component to use
useControllableStatefrom@radix-ui/react-use-controllable-state.
How to install state
Manually: put the files in place
.claude/rules/state.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/state.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/state.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/state.mdManually: put the files in place
.clinerules/state.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about state
How do I install state in Claude Code?
Place the rule file at .claude/rules/state.md.
What does state do?
The rule describes a component API that supports both controlled and uncontrolled state. It uses useControllableState for the combined pattern.
What does state require to work?
The combined state pattern requires @radix-ui/react-use-controllable-state.
Source text
state.md · Apache-2.0
---
title: State Management Patterns
impact: HIGH
impactDescription: Flexible component APIs for all use cases
tags: state, controlled, uncontrolled, useControllableState, radix
---
## State Management Patterns
Build flexible components that work seamlessly in both controlled and uncontrolled modes.
### Uncontrolled State
Component manages its own state internally:
```tsx
export const Stepper = () => {
const [value, setValue] = useState(0);
return (
<div>
<p>{value}</p>
<button onClick={() => setValue(value + 1)}>Increment</button>
</div>
);
};
```
**When to use:** Simple components, default behavior, internal state is sufficient.
### Controlled State
Parent component manages the state:
```tsx
type StepperProps = {
value: number;
setValue: (value: number) => void;
};
export const Stepper = ({ value, setValue }: StepperProps) => (
<div>
<p>{value}</p>
<button onClick={() => setValue(value + 1)}>Increment</button>
</div>
);
```
**When to use:** State coordination, external data sources, form validation, persistence.
### Merging Both Patterns
Use `@radix-ui/react-use-controllable-state` to support both:
```tsx
import { useControllableState } from "@radix-ui/react-use-controllable-state";
type StepperProps = {
value?: number;
defaultValue?: number;
onValueChange?: (value: number) => void;
};
export const Stepper = ({
value: controlledValue,
defaultValue,
onValueChange,
}: StepperProps) => {
const [value, setValue] = useControllableState({
prop: controlledValue,
defaultProp: defaultValue,
onChange: onValueChange,
});
return (
<div>
<p>{value}</p>
<button onClick={() => setValue(value + 1)}>Increment</button>
</div>
);
};
```
**Usage:**
```tsx
// Uncontrolled
<Stepper defaultValue={0} />;
// Controlled
const [count, setCount] = useState(5);
<Stepper value={count} onValueChange={setCount} />;
```
### Prop Naming Conventions
| State Type | Value Prop | Default Prop | Change Callback |
| ---------- | ---------- | ----------------- | ------------------ |
| Generic | `value` | `defaultValue` | `onValueChange` |
| Boolean | `checked` | `defaultChecked` | `onCheckedChange` |
| Open/Close | `open` | `defaultOpen` | `onOpenChange` |
| Selection | `selected` | `defaultSelected` | `onSelectedChange` |
### Complete Example: Toggle
```tsx
import { useControllableState } from "@radix-ui/react-use-controllable-state";
type ToggleProps = {
checked?: boolean;
defaultChecked?: boolean;
onCheckedChange?: (checked: boolean) => void;
disabled?: boolean;
};
export const Toggle = ({
checked: controlledChecked,
defaultChecked,
onCheckedChange,
disabled,
}: ToggleProps) => {
const [checked, setChecked] = useControllableState({
prop: controlledChecked,
defaultProp: defaultChecked ?? false,
onChange: onCheckedChange,
});
return (
<button
type="button"
role="switch"
aria-checked={checked}
disabled={disabled}
onClick={() => !disabled && setChecked(!checked)}
>
{checked ? "On" : "Off"}
</button>
);
};
```
### Best Practices
**1. Always Make Props Optional:**
```tsx
// ✅ Supports both patterns
type Props = {
value?: number;
defaultValue?: number;
onValueChange?: (value: number) => void;
};
```
**2. Provide Sensible Defaults:**
```tsx
const [value, setValue] = useControllableState({
prop: controlledValue,
defaultProp: defaultValue ?? 0,
onChange: onValueChange,
});
```
**3. Handle onChange in Both Modes:**
The `onChange` callback should fire regardless of controlled/uncontrolled mode.
### Key Benefits
1. **Flexibility** - Works in both controlled and uncontrolled modes
2. **Developer Experience** - Simple API for simple cases, powerful for complex
3. **Consistency** - Matches patterns used by Radix UI and professional libraries
4. **Backward Compatibility** - Easy to migrate from uncontrolled to controlled
© maxtrigify · Apache-2.0 · maxtrigify/Otto