[ React ] 비제어/제어 상태에 대해 알아보자. (feat. @radix-ui/useControllableState)

github.com/radix-ui/react-useControllableState 소스코드

primitives/packages/react/use-controllable-state/src/useControllableState.tsx at main · radix-ui/primitives

 

 

🕹️ useControllableState() 란?

Radix 라이브러리에서 제공하는 React 훅으로, 제어된(controllable) 상태와 내부 상태를 동시에 관리하는 Hook이다.

즉, 부모 컴포넌트에서 상태를 직접 관리할 수도 있고, 상태가 제공되지 않았을 경우 내부적으로 상태를 관리하는 방식이다.

"Controlled + Uncontrolled" 상태 관리 패턴을 구현할 때 유용하다.

 

🤔 왜 useControllableState()가 필요해?

React 컴포넌트에서 상태를 관리할 때 제어된 상태와 비제어 상태 두 가지 방식이 있다.

 

🟢 제어된 상태(Controllable)

상태를 부모에서 직접 관리하고, value와 onChange를 props로 전달하여 동작

function Parent() {
  const [value, setValue] = React.useState("");

  return <Input value={value} onChange={setValue} />;
}

여기서 Input 컴포넌트는 완전히 제어된 상태를 따르게 된다.

 

🔴 비제어된 상태 (Uncontrolled)

useState()를 이용해 컴포넌트 내부에서 자체적으로 상태를 관리하다.

function Input() {
  const [value, setValue] = React.useState("");

  return <input value={value} onChange={(e) => setValue(e.target.value)} />;
}

여기서 Input 내부에서 상태를 관리하므로 외부에서 제어할 수 없다.

 

하지만,

이 두가지 방식을 모두 지원하는 하이브리드 방식이 필요할 때가 있다.

👉 useControllableState()를 사용하면 부모에서 상태를 제공하면 Controlled, 제공하지 않으면 Uncontrolled 상태로 동작하게 만들 수 있다.

 

즉, 부모가 자식의 상태를 관리하도록 상태를 내려줄 수도 있고, 자식내에서 단독으로 상태를 관리할 수 있다.

 

해당 Hook을 사용하려면 우선 Radix에서 다운 받아야한다.

npm install @radix-ui/react-use-controllable-state

 

🧩 useControllableState() 뜯어보기

github.com/radix-ui/primitives/use-controllableState

primitives/packages/react/use-controllable-state/src/useControllableState.tsx at main · radix-ui/primitives

코드는 다음과 같다

 

(useContollableState()에 사용된 useCallbackRef()의 설명을 원하면 펼쳐서 보기)

참고

github.com/radix-ui/primitives/useCallbackRef

primitives/packages/react/use-callback-ref/src/useCallbackRef.tsx at main · radix-ui/primitives

 

import * as React from 'react';

/**
 * A custom hook that converts a callback to a ref to avoid triggering re-renders when passed as a
 * prop or avoid re-executing effects when passed as a dependency
 */
function useCallbackRef<T extends (...args: any[]) => any>(callback: T | undefined): T {
  // 콜백 함수가가 들어오면 함수를 Ref 저장.
  // 콜백 함수가 변경되어도 리렌더링을 방지.
  const callbackRef = React.useRef(callback);

  React.useEffect(() => {
    // useEffect()를 사용하여 callback이 변경될 때마다 callbackRef.current를 업데이트
    // 의존성 배열이 없기 때문에 모든 렌더링 이후 실행.
    callbackRef.current = callback;
  });

  // https://github.com/facebook/react/issues/19240
  // useMemo()를 사용하여 새로운 함수를 반환
  // 의존성이 비어 있으므로, 이 함수는 한 번만 생성
  // 결과적으로 useCallbackRef가 반환하는 함수는 처음 생성된 이후 변경되지 않음.
  // 하지만 callbackRef.current가 콜백 함수를 참조하기 때문에 최신 콜백을 유지.
  return React.useMemo(() => (
    (...args) => callbackRef.current?.(...args)) as T
   ,[]);
}

export { useCallbackRef };

 

🤔 useCallback과의 차이

const memoizedCallback = useCallback(() => {
  console.log("callback 실행!");
}, [dependency]); // dependency가 바뀔 때마다 함수가 새로 생성됨

dependency가 변경될 때마다 새로운 함수가 생성 👉 useEffect의 의존성 배열에 있으면 불필요한 재실행 발생

 

const stableCallback = useCallbackRef(() => {
  console.log("callback 실행!");
});

useCallbackRef를 사용하면 최초에 생성된 함수가 유지됨.

하지만 내부적으로는 최신 콜백을 참조하고 있어 최신 로직을 실행 가능

 

🤔 언제 사용하면 좋을까?

1. 콜백 함수를 ref로 저장하고 최신 상태를 유지하면서도 불필요한 재생성을 방지하고 싶을 때

2. 콜백 함수를 prop으로 넘길 때, 불필요한 리렌더링을 방지하고 싶을 때

3. useEffect 의존성 배열에 콜백 함수를 넣고 싶지만, 콜백 변경으로 인해 불필요한 재실행을 방지하고 싶을 때

 

✅ 결론

1. 콜백이 변경되더라도 함수 참조가 유지

2. 불필요한 리렌더링 방지 (prop으로 전달 시 유용)

3. useEffect 등의 의존성 배열에서 안전하게 사용 가능

4. 최신 상태의 콜백을 유지하면서도 안정적인 참조 제공

 

React에서 최신 콜백을 유지하면서도 불필요한 리렌더링을 방지하는 최적화된 코드를 작성할 수 있다.

 

---

import * as React from 'react';
import { useCallbackRef } from '@radix-ui/react-use-callback-ref';

// params는
// prop (제어할 값)
// defaultProp (제어할 값의 기본 값)
// onChange (제어할 값을 제어할 함수)
type UseControllableStateParams<T> = {
  prop?: T | undefined;
  defaultProp?: T | undefined;
  onChange?: (state: T) => void;
};

// setState 타입 정의
type SetStateFn<T> = (prevState?: T) => T;

function useControllableState<T>({
  prop,
  defaultProp,
  onChange = () => {},
}: UseControllableStateParams<T>) {
  // 비제어일 경우, useUncontrollableState() 적용
  const [uncontrolledProp, setUncontrolledProp] = useUncontrolledState({ defaultProp, onChange });

  // prop값이 넘어오면 제어 상태, undefined라면 비제어로 값 선언
  const isControlled = prop !== undefined;
  
  // 제어 상태면 prop을 사용, 그렇지 않다면 비제어의 값을 적용
  const value = isControlled ? prop : uncontrolledProp;
  
  // onChange 최적화
  const handleChange = useCallbackRef(onChange);

  const setValue: React.Dispatch<React.SetStateAction<T | undefined>> = React.useCallback(
    (nextValue) => {
      if (isControlled) {
        const setter = nextValue as SetStateFn<T>;
        const value = typeof nextValue === 'function' ? setter(prop) : nextValue;
        if (value !== prop) handleChange(value as T);
      } else {
        setUncontrolledProp(nextValue);
      }
    },
    [isControlled, prop, setUncontrolledProp, handleChange]
  );

  return [value, setValue] as const;
}

function useUncontrolledState<T>({
  defaultProp,
  onChange,
}: Omit<UseControllableStateParams<T>, 'prop'>) {
  const uncontrolledState = React.useState<T | undefined>(defaultProp);
  const [value] = uncontrolledState;
  const prevValueRef = React.useRef(value);
  const handleChange = useCallbackRef(onChange);

  React.useEffect(() => {
    if (prevValueRef.current !== value) {
      handleChange(value as T);
      prevValueRef.current = value;
    }
  }, [value, prevValueRef, handleChange]);

  return uncontrolledState;
}

export { useControllableState };

 

🔍 useState와 비교

Feature	useState()	useControllableState()
제어된 상태 지원	❌ (외부에서 관리 불가)	✅ (prop으로 관리 가능)
비제어 상태 지원	✅ (내부에서 관리 가능)	✅ (defaultProp 사용 가능)
혼합 사용 가능	❌ (수동으로 처리해야 함)	✅ (자동으로 전환됨)
부모 상태 변화 반응	❌ (수동으로 업데이트 필요)	✅ (자동 반영)

 

 

📄 사용법

기본 구조는 다음과 같다

컨트롤 될 자식 컴포넌트에 다음과 같이 할당한다.

const [state, setState] = useControllableState({
  prop: controlledValue, // 제어된 상태 값
  onChange: onChange, // 변경 시 실행될 함수
  defaultProp: defaultValue, // 내부적으로 사용할 기본 상태
});

const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
  setInputValue(event.target.value);
};

∙ prop: props로 넘겨받는 prop값 (Controlled).

∙ defaultProp: prop의 기본 상태값 (Uncontrolled).

∙ onChange: 실행할 콜백 함수.

 

그리고 useControllableState()로 받는 setState()를 실행해주면 된다.

 

다시 한 번 말하면, 부모로부터, prop과 onChange를 받으면 제어, 받지 않았다면 비제어 방식으로 동작한다.

* 작성하면서 헷갈렸는데 여기서 제어/비제어는 부모가 자식을 컨트롤할지 말지의 여부이다.

(왜냐하면.. 메모리에 관하여 제어/비제어 계속 헷갈려서 이것도 리렌더링 되는데 왜...? 이러고 있었다..... 하아.....)

 

💻 예시코드

"use client";

import { useControllableState } from "@radix-ui/react-use-controllable-state";

import React, { useState } from "react";

type InputProps = {
  value?: string;
  onChange?: (value: string) => void;
  defaultValue?: string;
};

function Input({ value, onChange, defaultValue }: InputProps) {
  const [inputValue, setInputValue] = useControllableState({
    prop: value,
    onChange: onChange,
    defaultProp: defaultValue,
  });

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    console.log("비제어");
    setInputValue(e.target.value);
  };

  return (
    <div className="flex items-center relative">
      <input
        value={inputValue}
        onChange={handleChange}
        className="pl-8 border rounded-md p-2"
      />
    </div>
  );
}

export default function Parent() {
  const [value, setValue] = useState("");

  const handleChange = (value: string) => {
    console.log("제어");
    setValue(value);
  };

  return (
    <div className="flex items-center">
      <Input value={value} onChange={handleChange} defaultValue={value} />
    </div>
  );
}

 

코드를 복사 붙여넣기 한 후, <Parent/>컴포넌트에서 <Input/>을 호출할 때, props를

∙ 제어: value, onChange() 두 개

∙ 비제어: defaultValue 한 개

∙ 하이브리드: value, onChnage(), defalutValue 세 개

 

에 변화를 주어가면서 개발자 도구 - Console을 확인해보면 이해하기 쉽다.

 

👀  결론

부모로부터 넘겨주는 값에 따라서 호출하는 컴포넌트를 제어할지 비제어할지 도와주는 Hook이다.