Skip to content

docs: update documentation #1236

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jul 10, 2025
Merged

docs: update documentation #1236

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7a56faf
docs: update documentation
lumirbot Jul 10, 2025
10aca03
refactor: translate Callout component
lumirlumir Jul 10, 2025
000dcb2
docs: update `forwardRef.md`
lumirlumir Jul 10, 2025
8ed6bf2
chore: update `.gitignore` to include editor config files
lumirlumir Jul 10, 2025
117d46a
docs: update `useImperativeHandle.md`
lumirlumir Jul 10, 2025
b54f43e
chore: remove unnecessary `2-suggestion.yml`
lumirlumir Jul 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 0 additions & 34 deletions .github/ISSUE_TEMPLATE/2-suggestion.yml
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,3 +39,8 @@ public/fonts/**/Optimistic_*.woff2

# rss
public/rss.xml

# code editor
.cursor
.idea
*.code-workspace
7 changes: 0 additions & 7 deletions VScode.code-workspace
View file
Open in desktop

This file was deleted.

6 changes: 3 additions & 3 deletions src/components/MDX/ExpandableCallout.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ interface ExpandableCalloutProps {

const variantMap = {
deprecated: {
title: '더 이상 사용되지 않습니다',
title: '더 이상 사용되지 않습니다!',
Icon: IconWarning,
containerClasses: 'bg-red-5 dark:bg-red-60 dark:bg-opacity-20',
textColor: 'text-red-50 dark:text-red-40',
Expand All @@ -53,7 +53,7 @@ const variantMap = {
'linear-gradient(rgba(245, 249, 248, 0), rgba(245, 249, 248, 1)',
},
experimental: {
title: 'Experimental Feature',
title: '실험적 기능',
Icon: IconCanary,
containerClasses:
'bg-green-5 dark:bg-green-60 dark:bg-opacity-20 text-primary dark:text-primary-dark text-lg',
Expand All @@ -70,7 +70,7 @@ const variantMap = {
'linear-gradient(rgba(249, 247, 243, 0), rgba(249, 247, 243, 1)',
},
wip: {
title: '개발중이에요',
title: '개발중이에요!',
Icon: IconNote,
containerClasses: 'bg-yellow-5 dark:bg-yellow-60 dark:bg-opacity-20',
textColor: 'text-yellow-50 dark:text-yellow-40',
Expand Down
50 changes: 25 additions & 25 deletions src/content/reference/react/forwardRef.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@ title: forwardRef

<Deprecated>

In React 19, `forwardRef` is no longer necessary. Pass `ref` as a prop instead.
React 19부터는 더 이상 `forwardRef`이 필요하지 않습니다. 이제 `ref`를 Prop으로 직접 전달하면 됩니다.

`forwardRef` will deprecated in a future release. Learn more [here](/blog/2024/04/25/react-19#ref-as-a-prop).
`forwardRef`는 향후 릴리스에서 사용 중단<sup>Deprecated</sup>될 예정입니다. 자세한 내용은 [여기](/blog/2024/12/05/react-19#ref-as-a-prop)에서 확인하세요.

</Deprecated>

<Intro>

`forwardRef`를 사용하면 컴포넌트가 [ref](/learn/manipulating-the-dom-with-refs)를 사용하여 부모 컴포넌트의 DOM 노드를 노출할 수 있습니다.
`forwardRef`를 사용하면 컴포넌트가 [Ref](/learn/manipulating-the-dom-with-refs)를 사용하여 부모 컴포넌트의 DOM 노드를 노출할 수 있습니다.

```js
const SomeComponent = forwardRef(render)
Expand All @@ -28,7 +28,7 @@ const SomeComponent = forwardRef(render)

### `forwardRef(render)` {/*forwardref*/}

컴포넌트가 ref를 받아 하위 컴포넌트로 전달하도록 하려면 `forwardRef()`를 호출하세요.
컴포넌트가 Ref를 받아 하위 컴포넌트로 전달하도록 하려면 `forwardRef()`를 호출하세요.

```js
import { forwardRef } from 'react';
Expand All @@ -42,22 +42,22 @@ const MyInput = forwardRef(function MyInput(props, ref) {

#### 매개변수 {/*parameters*/}

* `render`: 컴포넌트의 렌더링 함수입니다. React는 컴포넌트가 부모로부터 받은 props와 `ref`로 이 함수를 호출합니다. 반환하는 JSX는 컴포넌트의 결과가 됩니다.
* `render`: 컴포넌트의 렌더링 함수입니다. React는 컴포넌트가 부모로부터 받은 `props`와 `ref`로 이 함수를 호출합니다. 반환하는 JSX는 컴포넌트의 결과가 됩니다.

#### 반환값 {/*returns*/}

`forwardRef`는 JSX에서 렌더링할 수 있는 React 컴포넌트를 반환합니다. 일반 함수로 정의된 React 컴포넌트와 다르게, `forwardRef`가 반환하는 컴포넌트는 `ref` prop도 받을 수 있습니다.
`forwardRef`는 JSX에서 렌더링할 수 있는 React 컴포넌트를 반환합니다. 일반 함수로 정의된 React 컴포넌트와 다르게, `forwardRef`가 반환하는 컴포넌트는 `ref` Prop도 받을 수 있습니다.

#### 주의 사항 {/*caveats*/}

* Strict Mode에서 React는 [실수로 발생한 결함을 찾기 위해](/reference/react/useState#my-initializer-or-updater-function-runs-twice) **렌더링 함수를 두 번 호출**합니다. 이는 개발 환경 전용 동작이며 프로덕션 환경에는 영향을 미치지 않습니다. 렌더링 함수가 순수함수인 경우(그래야만 합니다.) 컴포넌트 로직에 영향을 미치지 않습니다. 호출 결과 중 하나의 결과는 무시됩니다.
* Strict Mode에서 React는 [실수로 발생한 결함을 찾기 위해](/reference/react/useState#my-initializer-or-updater-function-runs-twice) **렌더링 함수를 두 번 호출**합니다. 이는 개발 환경 전용 동작이며 프로덕션 환경에는 영향을 미치지 않습니다. 렌더링 함수가 순수 함수인 경우(그래야만 합니다), 컴포넌트 로직에 영향을 미치지 않습니다. 호출 결과 중 하나의 결과는 무시됩니다.


---

### `render` 함수 {/*render-function*/}

`forwardRef`는 `render` 함수를 인수로 받습니다. React는 `props`와 `ref`와 함께 이 함수를 호출합니다.
`forwardRef`는 `render` 함수를 인수로 받습니다. React는 `props` 및 `ref`와 함께 이 함수를 호출합니다.

```js
const MyInput = forwardRef(function MyInput(props, ref) {
Expand All @@ -72,21 +72,21 @@ const MyInput = forwardRef(function MyInput(props, ref) {

#### 매개변수 {/*render-parameters*/}

* `props`: 부모 컴포넌트가 전달한 props입니다.
* `props`: 부모 컴포넌트가 전달한 Props입니다.

* `ref`: 부모 컴포넌트가 전달한 `ref` 어트리뷰트입니다. `ref`는 객체나 함수일 수 있습니다. 부모 컴포넌트가 ref를 전달하지 않은 경우 `null`이 됩니다. 전달받은 `ref`를 다른 컴포넌트에 전달하거나 [`useImperativeHandle`.](/reference/react/useImperativeHandle)에 전달해야 합니다.
* `ref`: 부모 컴포넌트가 전달한 `ref` 어트리뷰트입니다. `ref`는 객체나 함수일 수 있습니다. 부모 컴포넌트가 Ref를 전달하지 않은 경우 `null`이 됩니다. 전달받은 `ref`를 다른 컴포넌트에 전달하거나 [`useImperativeHandle`](/reference/react/useImperativeHandle)에 전달해야 합니다.

#### 반환값 {/*render-returns*/}

`forwardRef`는 JSX에서 렌더링할 수 있는 React 컴포넌트를 반환합니다. 일반 함수로 정의된 React 컴포넌트와 다르게 `forwardRef` 에 의해 반환되는 컴포넌트는 `ref` prop를 받을 수 있습니다.
`forwardRef`는 JSX에서 렌더링할 수 있는 React 컴포넌트를 반환합니다. 일반 함수로 정의된 React 컴포넌트와 다르게 `forwardRef`에 의해 반환되는 컴포넌트는 `ref` Prop를 받을 수 있습니다.

---

## 사용법 {/*usage*/}

### 부모 컴포넌트에 DOM 노드 노출하기 {/*exposing-a-dom-node-to-the-parent-component*/}

기본적으로 각 컴포넌트의 DOM 노드는 비공개입니다. 그러나 때로는 부모에 DOM 노드를 노출하는 것이 유용할 수 있습니다. 예를 들어 focus 하기 위해 노출할 수 있습니다. 이를 위해 컴포넌트 정의를 `forwardRef()`로 감싸주면 됩니다.
기본적으로 각 컴포넌트의 DOM 노드는 비공개입니다. 그러나 때로는 부모에 DOM 노드를 노출하는 것이 유용할 수 있습니다. 예를 들어 포커스<sup>Focus</sup> 하기 위해 노출할 수 있습니다. 이를 위해 컴포넌트 정의를 `forwardRef()`로 감싸주면 됩니다.

```js {3,11}
import { forwardRef } from 'react';
Expand All @@ -102,7 +102,7 @@ const MyInput = forwardRef(function MyInput(props, ref) {
});
```

props 다음에 두 번째 인수로 <CodeStep step={1}>ref</CodeStep>를 받게 됩니다. 노출하려는 DOM 노드에 이를 전달합니다.
`props` 다음에 두 번째 인수로 <CodeStep step={1}>ref</CodeStep>를 받게 됩니다. 노출하려는 DOM 노드에 이를 전달합니다.

```js {8} [[1, 3, "ref"], [1, 8, "ref", 30]]
import { forwardRef } from 'react';
Expand Down Expand Up @@ -139,15 +139,15 @@ function Form() {
}
```

이 `Form` 컴포넌트는 `MyInput` 에게 [ref를 전달](/reference/react/useRef#manipulating-the-dom-with-a-ref)합니다. `MyInput` 컴포넌트는 해당 ref를 `<input>` 태그에 전달합니다. 결과적으로 `Form` 컴포넌트는 해당 `<input>` DOM 노드에 접근하여 [`focus()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus)를 호출할 수 있습니다.
이 `Form` 컴포넌트는 `MyInput` 에게 [Ref를 전달](/reference/react/useRef#manipulating-the-dom-with-a-ref)합니다. `MyInput` 컴포넌트는 해당 Ref를 `<input>` 태그에 전달합니다. 결과적으로 `Form` 컴포넌트는 해당 `<input>` DOM 노드에 접근하여 [`focus()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus)를 호출할 수 있습니다.

컴포넌트 내부의 DOM 노드의 ref를 노출하면 나중에 컴포넌트의 내부를 변경하기가 더 어려워진다는 점에 유의하세요. 일반적으로 버튼이나 텍스트 input과 같이 재사용할 수 있는 저수준 컴포넌트에서 DOM 노드를 노출하지만, 아바타나 댓글 같은 애플리케이션 레벨의 컴포넌트에서는 노출하고 싶지 않을 것입니다.
컴포넌트 내부 DOM 노드의 Ref를 노출하면 나중에 컴포넌트의 내부를 변경하기가 더 어려워진다는 점에 유의하세요. 일반적으로 버튼이나 텍스트 Input과 같이 재사용할 수 있는 저수준 컴포넌트에서 DOM 노드를 노출하지만, 아바타나 댓글 같은 애플리케이션 레벨의 컴포넌트에서는 노출하고 싶지 않을 것입니다.

<Recipes title="ref 전달 예시">

#### 텍스트 input에 초점 맞추기 {/*focusing-a-text-input*/}
#### 텍스트 Input에 초점 맞추기 {/*focusing-a-text-input*/}

버튼을 클릭하면 input에 포커스 됩니다. `Form` 컴포넌트는 ref를 정의하고 이를 `MyInput` 컴포넌트로 전달합니다. `MyInput` 컴포넌트는 해당 ref를 `input`으로 전달합니다. 이렇게 하면 `Form` 컴포넌트가 `input`의 포커스를 줄 수 있습니다.
버튼을 클릭하면 Input에 포커스됩니다. `Form` 컴포넌트는 Ref를 정의하고 이를 `MyInput` 컴포넌트로 전달합니다. `MyInput` 컴포넌트는 해당 Ref를 `input`으로 전달합니다. 이렇게 하면 `Form` 컴포넌트가 `input`에 포커스를 줄 수 있습니다.

<Sandpack>

Expand Down Expand Up @@ -201,7 +201,7 @@ input {

#### 비디오 재생 및 정지하기 {/*playing-and-pausing-a-video*/}

버튼을 클릭하면 `<video>` DOM 노드에서 [`play()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/play) 및 [`pause()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/pause)를 호출합니다. `App` 컴포넌트는 ref를 정의하고 이를 `MyVideoPlayer` 컴포넌트에 전달합니다. `MyVideoPlayer` 컴포넌트는 해당 ref를 브라우저 `<video>` 노드로 전달합니다. 이렇게 하면 `App` 컴포넌트가 `<video>`를 재생하고 정지할 수 있습니다.
버튼을 클릭하면 `<video>` DOM 노드에서 [`play()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/play) 및 [`pause()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/pause)를 호출합니다. `App` 컴포넌트는 Ref를 정의하고 이를 `MyVideoPlayer` 컴포넌트에 전달합니다. `MyVideoPlayer` 컴포넌트는 해당 Ref를 브라우저 `<video>` 노드로 전달합니다. 이렇게 하면 `App` 컴포넌트가 `<video>`를 재생하고 정지할 수 있습니다.

<Sandpack>

Expand Down Expand Up @@ -260,7 +260,7 @@ button { margin-bottom: 10px; margin-right: 10px; }

---

### 여러 컴포넌트를 통해 ref 전달하기 {/*forwarding-a-ref-through-multiple-components*/}
### 여러 컴포넌트를 통해 Ref 전달하기 {/*forwarding-a-ref-through-multiple-components*/}

`ref`를 DOM 노드로 전달하지 않고 `MyInput`과 같은 컴포넌트로 전달할 수 있습니다.

Expand All @@ -276,7 +276,7 @@ const FormField = forwardRef(function FormField(props, ref) {
});
```

`MyInput` 컴포넌트가 `<input>`에 ref를 전달하면 `FormField`의 ref는 해당 `<input>`을 얻을 수 있습니다.
`MyInput` 컴포넌트가 `<input>`에 `ref`를 전달하면 `FormField`의 `ref`는 해당 `<input>`을 얻을 수 있습니다.

```js {2,5,10}
function Form() {
Expand All @@ -297,7 +297,7 @@ function Form() {
}
```

`Form` 컴포넌트는 ref를 정의하고 이를 `FormField`에 전달합니다. `FormField` 컴포넌트는 해당 ref를 `MyInput`으로 전달하고, 이 컴포넌트는 `<input>` DOM 노드로 전달합니다. 이것이 `Form`이 `<input>` DOM 노드에 접근하는 방식입니다.
`Form` 컴포넌트는 Ref를 정의하고 이를 `FormField`에 전달합니다. `FormField` 컴포넌트는 해당 Ref를 `MyInput`으로 전달하고, 이 컴포넌트는 `<input>` DOM 노드로 전달합니다. 이것이 `Form`이 `<input>` DOM 노드에 접근하는 방식입니다.


<Sandpack>
Expand Down Expand Up @@ -377,7 +377,7 @@ input, button {

### DOM 노드 대신 명령형 핸들 노출하기 {/*exposing-an-imperative-handle-instead-of-a-dom-node*/}

전체 DOM 노드를 노출하는 대신 제한된 메서드 집합과 함께 *명령형 핸들*이라고 하는 사용자 정의 객체를 노출할 수 있습니다. 이를 위해 DOM 노드를 보유할 별도의 ref를 정의해야 합니다.
전체 DOM 노드를 노출하는 대신 제한된 메서드 집합과 함께 *명령형 핸들*이라고 하는 사용자 정의 객체를 노출할 수 있습니다. 이를 위해 DOM 노드를 보유할 별도의 Ref를 정의해야 합니다.

```js {2,6}
const MyInput = forwardRef(function MyInput(props, ref) {
Expand Down Expand Up @@ -412,7 +412,7 @@ const MyInput = forwardRef(function MyInput(props, ref) {
});
```

일부 컴포넌트가 `MyInput`의 ref를 받으면 DOM 노드 대신 `{ focus, scrollIntoView }` 객체만 받습니다. 이를 통해 노출하는 DOM 노드의 정보를 최소한으로 제한할 수 있습니다.
일부 컴포넌트가 `MyInput`의 Ref를 받으면 DOM 노드 대신 `{ focus, scrollIntoView }` 객체만 받습니다. 이를 통해 노출하는 DOM 노드의 정보를 최소한으로 제한할 수 있습니다.

<Sandpack>

Expand Down Expand Up @@ -502,7 +502,7 @@ const MyInput = forwardRef(function MyInput({ label }, ref) {
});
```

이 문제를 해결하려면 `ref`를 DOM 노드나 ref를 받을 수 있는 다른 컴포넌트에 전달하세요.
이 문제를 해결하려면 `ref`를 DOM 노드나 `ref`를 받을 수 있는 다른 컴포넌트에 전달하세요.

```js {1,5}
const MyInput = forwardRef(function MyInput({ label }, ref) {
Expand All @@ -528,7 +528,7 @@ const MyInput = forwardRef(function MyInput({ label, showInput }, ref) {
});
```

`showInput`이 `false`이면 ref가 어떤 노드로도 전달되지 않으며 `MyInput`의 ref는 비어 있게 됩니다. 이 예시의 `Panel`과 같이 조건이 다른 컴포넌트 안에 숨겨져 있는 경우 특히 이 점을 놓치기 쉽습니다.
`showInput`이 `false`이면 `ref`가 어떤 노드로도 전달되지 않으며 `MyInput`의 `ref`는 비어 있게 됩니다. 이 예시의 `Panel`과 같이 조건이 다른 컴포넌트 안에 숨겨져 있는 경우 특히 이 점을 놓치기 쉽습니다.

```js {5,7}
const MyInput = forwardRef(function MyInput({ label, showInput }, ref) {
Expand Down
Loading