Skip to main content
rule CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/state.md
Open on GitHub

What 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 value and defaultValue in 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, and onCheckedChange to Toggle.
  • Refactor this component to use useControllableState from @radix-ui/react-use-controllable-state.

How to install state

Manually: put the files in place

.claude/rules/state.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

IDE rules catalog →

From the same set18

The whole set →
data-attributes data-attributes is a Claude Code rule for styling component states and targeting nested parts with data-state and data-slot. CX Codex +1 ★ 141repo stars principles The principles rule for Claude Code establishes six core standards for component design. It guides agents during component creation, refactoring, and evaluation. CX Codex +1 ★ 141repo stars as-child as-child is a Claude Code rule for merging a component’s props and handlers into a custom child without an extra DOM wrapper. It applies to composable React triggers. CX Codex +1 ★ 141repo stars documentation documentation is a Claude Code rule that standardizes UI component documentation. It enforces consistent sections for props, runnable examples, and accessibility guidelines. CX Codex +1 ★ 141repo stars accessibility accessibility is a Claude Code rule that enforces accessible frontend patterns. It triggers when generating UI components, dialogs, and navigation menus. CX Codex +1 ★ 141repo stars polymorphism polymorphism is a Claude Code rule for React components that keep their styles and behavior across element types. The as prop selects the rendered element. CX Codex +1 ★ 141repo stars styling styling is a Claude Code rule that enforces Tailwind CSS patterns. Guides the agent to combine classes with tailwind-merge, clsx, and CVA. CX Codex +1 ★ 141repo stars definitions definitions is a Claude Code rule that classifies UI artifacts and keeps names consistent across primitives, components, blocks, templates, and patterns. CX Codex +1 ★ 141repo stars

Project sponsors

Companies that keep this analytics open