React props 사용법 부모에서 자식으로 데이터 전달하는 구조

앞 예제는 App.jsx(JavaScript), 버튼 실습은 App.tsx(React + TypeScript)를 사용합니다. 내 PC에서 실행하기 전 React Vite 환경 준비를 확인하세요.

props 사용 예제

function Greeting({ name }) {
  return <p>안녕하세요, {name}님</p>;
}
export default function App() {
  return <Greeting name="해비" />;
}

화면 결과: 안녕하세요, 해비님

부모 App이 name="해비"를 전달하고, 자식 Greeting이 { name }으로 꺼내 표시합니다. 위 JavaScript 예제를 React 프로젝트의 src/App.jsx에서 실행할 수 있습니다.

props를 직접 수정하지 않습니다

부모가 새 값을 전달하면 자식의 화면도 갱신됩니다. 자식에서 받은 객체를 직접 바꾸는 아래 코드는 피하세요.

function TaskItem({ task }) {
  task.completed = true; // 잘못된 예: 받은 객체를 직접 수정
  return <li>{task.title}</li>;
}

객체에 대입하는 문법 자체는 실행될 수 있지만, props를 수정해도 React에 상태 변경을 알리지 못합니다. 변경 요청은 다음처럼 부모의 함수에 전달하세요.

클릭 요청은 함수로 전달합니다

function TaskItem({ task, onToggle }) {
  return (
    <button onClick={() => onToggle(task.id)}>
      {task.title}
    </button>
  );
}
// 부모의 JSX에서 사용
<TaskItem task={task} onToggle={(id) => console.log(id)} />

이 부분 코드는 부모에 task 객체가 있다고 가정합니다. 클릭하면 onToggle(task.id)이 실행되어 Console에 id를 출력합니다. 이 함수에는 상태를 바꾸는 코드가 없으므로 완료 여부는 바뀌지 않습니다.

TypeScript에서는 props 타입을 선언합니다

type GreetingProps = { name: string };
function Greeting({ name }: GreetingProps) {
  return <p>안녕하세요, {name}님</p>;
}

{ name }은 props 객체의 값을 꺼내는 구조 분해 문법입니다. props.name으로 읽어도 같습니다. JSX의 {name}은 그 값을 화면에 표시합니다.

객체와 콜백 함수의 타입 보기

type Task = {
  id: string;
  title: string;
  completed: boolean;
};
type TaskItemProps = {
  task: Task;
  onToggle: (id: string) => void;
  onDelete: (id: string) => void;
};

task는 표시할 객체이고, onToggle·onDelete는 작업 id를 받아 처리할 함수입니다. 타입 선언이 객체를 자동 동결하는 것은 아니므로 자식에서 직접 수정하지 않는 규칙도 지켜야 합니다.

자주 하는 실수

클릭할 함수를 즉시 실행하지 마세요

// 잘못된 예: 화면을 그릴 때 실행
<button onClick={onDelete(task.id)}>삭제</button>
// 수정: 클릭할 때 실행
<button onClick={() => onDelete(task.id)}>삭제</button>

인자가 필요하면 함수로 감싸고, 인자가 없는 함수는 onClick={handleClick}처럼 전달합니다.

부모와 자식의 prop 이름을 맞추세요

// 자식이 onDelete를 받는데 onRemove를 전달하면 연결되지 않음
<TaskItem task={task} onToggle={handleToggle} onRemove={handleDelete} />
// 수정
<TaskItem task={task} onToggle={handleToggle} onDelete={handleDelete} />

부모에서 정의한 함수의 이름은 handleDelete여도 괜찮습니다. 자식이 받는 prop 이름인 onDelete를 일치시켜야 합니다.

버튼으로 props 확인하기

type Task = { id: string; title: string; completed: boolean };
type TaskItemProps = { task: Task; onToggle: (id: string) => void };
function TaskItem({ task, onToggle }: TaskItemProps) {
  return (
    <button onClick={() => onToggle(task.id)}>
      {task.title}
    </button>
  );
}
export default function App() {
  const task: Task = { id: 'one', title: '책 읽기', completed: false };
  return (
    <TaskItem task={task} onToggle={(id) => console.log(id)} />
  );
}

<!doctype html>
<html lang="ko"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>TaskFlow</title></head><body><div id="root"></div><script type="module" src="/src/main.tsx"></script></body></html>

{
  "name": "taskflow-step-05-props",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "engines": {
    "node": ">=22.12.0"
  },
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "tsc --noEmit && vite build",
    "preview": "vite preview --host 127.0.0.1"
  },
  "dependencies": {
    "react": "19.3.0",
    "react-dom": "19.3.0"
  },
  "devDependencies": {
    "typescript": "7.0.2",
    "vite": "8.3.0",
    "@vitejs/plugin-react": "6.1.1",
    "@types/react": "19.3.0",
    "@types/react-dom": "19.3.0",
    "@types/node": "26.6.2"
  }
}

import Header from './components/Header';
import TaskList from './components/TaskList';
import type { Task } from './types/task';

const tasks: Task[] = [
  { id: 'task-1', title: 'props 구조 익히기', completed: true },
  { id: 'task-2', title: '이벤트 함수 전달하기', completed: false },
];

function App() {
  const handleToggle = (id: string) => {
    console.log('toggle', id);
  };

  const handleDelete = (id: string) => {
    console.log('delete', id);
  };

  return (
    <main className="app">
      <Header />
      <TaskList
        tasks={tasks}
        onToggle={handleToggle}
        onDelete={handleDelete}
      />
    </main>
  );
}

export default App;

export default function Header() {
  return (
    <header>
      <p className="eyebrow">React Learning Project</p>
      <h1>TaskFlow</h1>
      <p>오늘 할 일을 하나씩 정리해 보세요.</p>
    </header>
  );
}

import type { Task } from '../types/task';

type TaskItemProps = {
  task: Task;
  onToggle: (id: string) => void;
  onDelete: (id: string) => void;
};

export default function TaskItem({
  task,
  onToggle,
  onDelete,
}: TaskItemProps) {
  return (
    <li>
      <button type="button" onClick={() => onToggle(task.id)}>
        {task.completed ? '완료 취소' : '완료'}
      </button>

      <span>{task.title}</span>

      <button type="button" onClick={() => onDelete(task.id)}>
        삭제
      </button>
    </li>
  );
}

import TaskItem from './TaskItem';
import type { Task } from '../types/task';

type TaskListProps = {
  tasks: Task[];
  onToggle: (id: string) => void;
  onDelete: (id: string) => void;
};

export default function TaskList({
  tasks,
  onToggle,
  onDelete,
}: TaskListProps) {
  if (tasks.length === 0) {
    return <p>등록된 작업이 없습니다.</p>;
  }

  return (
    <section>
      <h2>작업 목록</h2>
      <ul>
        {tasks.map((task) => (
          <TaskItem
            key={task.id}
            task={task}
            onToggle={onToggle}
            onDelete={onDelete}
          />
        ))}
      </ul>
    </section>
  );
}

* {
  box-sizing: border-box;
}

body {
  margin: 0;
  font-family: Arial, sans-serif;
  color: #111;
  background: #f5f5f5;
}

.app {
  width: min(720px, calc(100% - 32px));
  margin: 48px auto;
}

.eyebrow {
  color: #666;
  font-size: 14px;
}

ul {
  padding-left: 20px;
}

button, input, select { min-height: 44px; font: inherit; }
button, input, select { border: 1px solid #aaa; padding: 8px 12px; }
button { cursor: pointer; }
button:disabled { cursor: wait; opacity: .6; }
ul { list-style: none; padding: 0; display: grid; gap: 12px; }
.task-card { border: 1px solid #ccc; padding: 16px; display: flex; gap: 12px; flex-wrap: wrap; align-items: center; }
.task-card__content, .task-card__actions { display: flex; gap: 12px; flex-wrap: wrap; align-items: center; }
form, section { margin-block: 20px; }
input:not([type="checkbox"]), select { max-width: 100%; }
details { margin-block: 24px; } summary { cursor: pointer; min-height: 44px; }
body { overflow-wrap: anywhere; }
[role="dialog"], [data-radix-popper-content-wrapper] { --radius: 0; }

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import './index.css';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

export type Task = {
  id: string;
  title: string;
  completed: boolean;
};

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": [
      "ES2022",
      "DOM",
      "DOM.Iterable"
    ],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "jsx": "react-jsx",
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "types": [
      "vite/client"
    ],
    "paths": {
      "@/*": [
        "./src/*"
      ]
    }
  },
  "include": [
    "src",
    "vite.config.ts"
  ]
}

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({ plugins: [react()] });

관련 학습과 문서

다음 글에서는 children으로 UI를 전달하는 방법을 다룹니다.

공식 문서

• React — Passing Props to a Component: 값 전달, 구조 분해 할당, props의 읽기 전용 규칙
• React — Responding to Events: 이벤트 함수 전달과 즉시 호출의 차이