API 레퍼런스
컴포넌트

공통 컴포넌트 (예시: <div>)

모든 내장 브라우저 컴포넌트 (예시: <div>)는 공통의 props와 이벤트를 지원합니다.

레퍼런스

공통 컴포넌트 (예시: <div>) 

<div className="wrapper">Some content</div>

아래의 예시를 더 참고하세요.

Props

아래의 특별한 React props 들은 내장된 모든 컴포넌트에서 지원합니다.

  • children: React 노드(엘리먼트, 문자열, 숫자, portal, null, undefined 그리고 불리언 타입과 같은 빈 노드, 또는 다른 React 노드의 배열) 입니다. 컴포넌트 내부의 콘텐츠를 지정합니다. JSX를 사용하면 일반적으로<div><span /></div>의 예시처럼 태그를 중첩하여 children prop를 암묵적으로 지정합니다.

  • dangerouslySetInnerHTML: 원시 HTML 문자열이 포함된{ __html: '<p>some html</p>' }형식의 객체입니다. DOM 노드의 innerHTML 프로퍼티를 덮어쓰고 전달된 HTML을 내부에 표시합니다. 이것은 매우 주의해서 사용해야 합니다. 내부 HTML을 신뢰할 수 없는 경우 (예시: 사용자 데이터를 기반으로 하는 경우) XSS 취약점이 발생할 수 있습니다. dangerouslySetInnerHTML에 대해 더 알아보려면 읽어보세요.

  • ref: useRef나 createRef의 ref 객체, 또는 ref 콜백 함수거나 legacy refs의 문자열입니다. 해당 ref는 해당 노드의 DOM 엘리먼트로 채워집니다. ref를 사용하여 DOM을 조작하는 방법에 대해 더 자세히 알아보세요.

  • suppressContentEditableWarning: 불리언 타입입니다. true 일 때, 일반적으로 같이 사용하지 않는 children과 contentEditable={true}가 모두 존재하는 엘리먼트에 대해 React에서 발생하는 경고를 나타내지 않습니다. 이는contentEditable 콘텐츠를 수동으로 관리하는 텍스트 입력 라이브러리를 빌드할 때 사용됩니다.

  • suppressHydrationWarning: 불리언 타입입니다. 서버 렌더링을 사용할 때, 일반적으로 서버와 클라이언트가 서로 다른 콘텐츠를 렌더링하면 경고가 표시됩니다. 일부 드문 사례(예시: 타임스탬프)에서는 정확한 일치를 보장하기가 매우 어렵거나 불가능합니다. suppressHydrationWarning를 true로 설정하면, React는 해당 엘리먼트의 어트리뷰트와 콘텐츠가 일치하지 않아도 경고를 표시하지 않습니다. 이는 한 단계의 깊이에서만 작동하며, 탈출구로 사용하기 위한 것입니다. 과도하게 사용하지 마세요. suppressing hydration 오류에 대해서 읽어보세요.

  • style: { fontWeight: 'bold', margin: 20 }와 같이 CSS 스타일이 있는 객체입니다. DOM의 style 프로퍼티에서 fontWeight 대신 font-weight로 작성하는 것과 마찬가지로 CSS 프로퍼티의 이름도 camelCase로 작성해야 합니다. 또한 문자열이나 숫자를 값으로 전달할 수 있습니다. width: 100와 같은 숫자를 전달한다면 React는 단위가 없는 프로퍼티가 아니라면 자동으로 px (“픽셀”)로 값을 추가합니다. style은 스타일 값을 미리 알 수 없는 동적 스타일에만 사용하는 것을 권장합니다. 그 외의 경우에는 className을 사용하여 일반 CSS 클래스를 사용하는 것이 더 효율적입니다. className과 style에 대해서 더 자세히 알아보세요.

아래의 표준 DOM props 들은 내장된 모든 컴포넌트에서 지원합니다.

사용자 정의 어트리뷰트를 props로 전달할 수도 있습니다. (예시: mycustomprop="someValue") 이는 서드파티 라이브러리와 통합할 때 유용할 수 있습니다. 사용자 정의 어트리뷰트의 이름은 소문자이어야 하며 on으로 시작하지 않아야 합니다. 값은 문자열로 변환됩니다. null 또는 undefined를 전달하면 사용자 정의 어트리뷰트가 제거됩니다.

다음의 이벤트는 <form> 엘리먼트에 대해서만 발생합니다.

다음의 이벤트는 <dialog> 엘리먼트에 대해서만 발생합니다. 그리고 브라우저 이벤트와 달리 React에서는 버블링이 발생합니다.

다음의 이벤트는 <details> 엘리먼트에 대해서만 발생합니다. 그리고 브라우저 이벤트와 달리 React에서는 버블이 발생합니다.

다음의 이벤트는 <img>, <iframe>, <object>, <embed>, <link> 그리고 SVG <image> 엘리먼트들에 대해서 발생합니다. 그리고 브라우저 이벤트와 달리 React에서는 버블링이 발생합니다.

다음의 이벤트는 <audio> 및 <video>와 같은 자원에 대해 발생합니다. 그리고 브라우저 이벤트와 달리 React에서는 버블이 발생합니다.

주의사항

  • children과 dangerouslySetInnerHTML을 동시에 전달할 수 없습니다.
  • 일부 이벤트(예시: onAbort, onLoad)는 브라우저에서 버블링이 발생하지 않지만, React에서는 버블링이 발생합니다.

ref 콜백 함수

useRef 에서 반환되는 ref 객체 대신 ref 속성에 함수를 전달할 수 있습니다.

<div ref={(node) => console.log(node)} />

ref 콜백에 대한 예시를 참조하세요.

<div> DOM 노드가 화면에 추가될 때, React는 node를 인수로 사용하여 ref 콜백을 호출합니다. 해당 <div> DOM 노드가 제거되면 React는 null을 인수로 사용하여 ref 콜백을 호출합니다.

React는 다른 ref 콜백을 전달할 때 마다 ref 콜백을 호출합니다. 위의 예시에서 (node) => { ... } 는 모든 렌더링에서 다른 함수입니다. 컴포넌트가 다시 렌더링 될 때, 이전 함수는 null을 인수로 사용하여 호출되고 다음 함수는 DOM 노드를 사용하여 호출됩니다.

매개변수

  • node: DOM 노드 또는 null입니다. React는 ref가 연결될 때 DOM 노드를 전달하고 ref가 분리되면 null을 전달합니다. 모든 렌더링에서 ref 콜백에 대해 동일한 함수를 전달하는 경우를 제외하고, 컴포넌트를 다시 렌더링할 마다 콜백이 일시적으로 분리되었다가 다시 연결됩니다.

반환 값

ref 콜백에서는 아무것도 반환하지 않습니다.

React 이벤트 객체

이벤트 핸들러는 React 이벤트 객체를 받게 되며, “합성 이벤트”라고도 합니다.

<button onClick={e => {
  console.log(e); // React 이벤트 객체
}} />

이것은 기본 DOM 이벤트와 같은 표준을 준수하지만 일부 브라우저의 불일치를 수정합니다.

일부 React의 이벤트는 브라우저의 네이티브 이벤트에 직접 매핑되지 않습니다. 예를 들어 onMouseLeave에서 e.nativeEvent는 mouseout 이벤트를 가리킵니다. 특정 매핑은 퍼블릭 API의 일부가 아니며 추후 변경될 수 있습니다. 어떠한 이유로 기본 브라우저 이벤트가 필요한 경우 e.nativeEvent에서 읽어와야 합니다.

프로퍼티

React 이벤트 객체는 표준 Event 프로퍼티의 일부를 구현했습니다.

  • bubbles: 불리언 타입입니다. 이벤트가 DOM을 통해 버블링되는지 여부를 반환합니다.
  • cancelable: 불리언 타입입니다. 이벤트를 취소할 수 있는지를 반환합니다.
  • currentTarget: DOM 노드입니다. React 트리에서 현재 핸들러가 연결된 노드를 반환합니다.
  • defaultPrevented: 불리언 타입입니다. preventDefault가 호출되었는지 여부를 반환합니다.
  • eventPhase: 숫자 타입입니다. 이벤트가 현재 어느 단계에 있는지 반환합니다.
  • isTrusted: 불리언 타입입니다. 사용자에 의해 이벤트가 시작되었는지에 대한 여부를 반환합니다.
  • target: DOM 노드입니다. (멀리 있는 자식일 수도 있는)이벤트가 발생한 노드를 반환합니다.
  • timeStamp: 숫자 타입입니다. 이벤트가 발생한 시간을 반환합니다.

추가로 React 이벤트 객체는 다음과 같은 프로퍼티를 제공합니다.

  • nativeEvent: DOM Event 이벤트입니다. 원래의 브라우저 이벤트 객체입니다.

메서드

React 이벤트 객체는 표준 Event 메서드의 일부를 구현 했습니다.

  • preventDefault(): 이벤트에 대한 기본 브라우저 동작을 방지합니다.
  • stopPropagation(): React 트리를 통한 이벤트 전파를 중지합니다.

추가로 React 이벤트 객체는 다음과 같은 프로퍼티를 제공합니다.

  • isDefaultPrevented(): preventDefault가 호출되었는지에 대한 여부를 나타내는 불리언 값을 반환합니다.
  • isPropagationStopped(): stopPropagation이 호출되었는지에 대한 여부를 나타내는 불리언 값을 반환합니다.
  • persist(): React DOM에서는 사용되지 않습니다. React Native에서는 이벤트가 발생한 후 이벤트의 프로퍼티를 읽으려면 해당 함수를 호출해야 합니다.
  • isPersistent(): React DOM에서는 사용되지 않습니다. React Native에서는 persist가 호출되었는지 여부를 반환합니다.

주의사항

  • currentTarget, eventPhase, target, type의 값은 React 코드가 예상하는 값을 반영합니다. 내부적으로는 React는 이벤트 핸들러를 루트에 첨부하지만, React 이벤트 객체에는 반영되지 않습니다. 예를 들어 e.currentTarget은 기본e.nativeEvent.currentTarget과 동일하지 않을 수 있습니다. 폴리필 된 이벤트의 경우 e.type (React 이벤트 타입)이 e.nativeEvent.type (기본 타입)과 다를 수 있습니다.

AnimationEvent 핸들러 함수

CSS 애니메이션 이벤트에 대한 이벤트 핸들러 유형입니다.

<div
  onAnimationStart={e => console.log('onAnimationStart')}
  onAnimationIteration={e => console.log('onAnimationIteration')}
  onAnimationEnd={e => console.log('onAnimationEnd')}
/>

매개변수

ClipboardEvent 핸들러 함수

클립보드의 API 이벤트에 대한 이벤트 핸들러 유형입니다.

<input
  onCopy={e => console.log('onCopy')}
  onCut={e => console.log('onCut')}
  onPaste={e => console.log('onPaste')}
/>

매개변수

CompositionEvent 핸들러 함수

입력 메서드 편집기 (IME) 이벤트에 대한 이벤트 핸들러 유형입니다.

<input
  onCompositionStart={e => console.log('onCompositionStart')}
  onCompositionUpdate={e => console.log('onCompositionUpdate')}
  onCompositionEnd={e => console.log('onCompositionEnd')}
/>

매개변수

DragEvent 핸들러 함수

HTML 드래그 앤 드롭 API 이벤트의 이벤트 핸들러 유형입니다.

<>
  <div
    draggable={true}
    onDragStart={e => console.log('onDragStart')}
    onDragEnd={e => console.log('onDragEnd')}
  >
    Drag source
  </div>

  <div
    onDragEnter={e => console.log('onDragEnter')}
    onDragLeave={e => console.log('onDragLeave')}
    onDragOver={e => { e.preventDefault(); console.log('onDragOver'); }}
    onDrop={e => console.log('onDrop')}
  >
    Drop target
  </div>
</>

매개변수

FocusEvent 핸들러 함수

포커싱 이벤트에 대한 이벤트 핸들러 유형입니다.

<input
  onFocus={e => console.log('onFocus')}
  onBlur={e => console.log('onBlur')}
/>

예시를 참조하세요.

매개변수

Event 핸들러 함수

일반 이벤트를 위한 이벤트 핸들러 유형입니다.

매개변수

InputEvent 핸들러 함수

onBeforeInput 이벤트에 대한 이벤트 핸들러 유형입니다.

<input onBeforeInput={e => console.log('onBeforeInput')} />

매개변수

KeyboardEvent 핸들러 함수

키보드 이벤트에 대한 이벤트 핸들러 유형입니다.

<input
  onKeyDown={e => console.log('onKeyDown')}
  onKeyUp={e => console.log('onKeyUp')}
/>

예시를 참조하세요.

매개변수

MouseEvent 핸들러 함수

마우스 이벤트에 대한 이벤트 핸들러 유형입니다.

<div
  onClick={e => console.log('onClick')}
  onMouseEnter={e => console.log('onMouseEnter')}
  onMouseOver={e => console.log('onMouseOver')}
  onMouseDown={e => console.log('onMouseDown')}
  onMouseUp={e => console.log('onMouseUp')}
  onMouseLeave={e => console.log('onMouseLeave')}
/>

예시를 참조하세요.

매개변수

PointerEvent 핸들러 함수

포인터 이벤트에 대한 이벤트 핸들러 유형입니다.

<div
  onPointerEnter={e => console.log('onPointerEnter')}
  onPointerMove={e => console.log('onPointerMove')}
  onPointerDown={e => console.log('onPointerDown')}
  onPointerUp={e => console.log('onPointerUp')}
  onPointerLeave={e => console.log('onPointerLeave')}
/>

예시를 참조하세요.

매개변수

TouchEvent 핸들러 함수

터치 이벤트에 대한 이벤트 핸들러 유형입니다.

<div
  onTouchStart={e => console.log('onTouchStart')}
  onTouchMove={e => console.log('onTouchMove')}
  onTouchEnd={e => console.log('onTouchEnd')}
  onTouchCancel={e => console.log('onTouchCancel')}
/>

매개변수

TransitionEvent 핸들러 함수

CSS 전환 이벤트에 대한 이벤트 핸들러 유형입니다.

<div
  onTransitionEnd={e => console.log('onTransitionEnd')}
/>

매개변수

UIEvent 핸들러 함수

일반적인 UI 이벤트를 위한 이벤트 핸들러 유형입니다.

<div
  onScroll={e => console.log('onScroll')}
/>

매개변수

WheelEvent 핸들러 함수

onWheel 이벤트에 대한 이벤트 핸들러 유형입니다.

<div
  onScroll={e => console.log('onScroll')}
/>

매개변수

사용법

CSS 스타일 적용하기

리액트는 className을 사용하여 CSS 클래스를 지정합니다. 이것은 HTML의 클래스 속성처럼 작동합니다.

<img className="avatar" />

그런 다음 별도의 CSS 파일에 CSS 규칙을 지정합니다.

/* In your CSS */
.avatar {
  border-radius: 50%;
}

React는 CSS 파일을 추가하는 방법을 규정하지 않습니다. 가장 간단한 방법은 HTML에 <link> 태그를 추가하는 것입니다. 빌드 도구나 프레임워크를 사용하고 있다면, 해당 기술의 문서를 참조하여 프로젝트에 CSS 파일을 추가하는 방법을 알아보세요.

때때로 스타일 값은 데이터에 따라 달라집니다. style 어트리뷰트를 사용하여 일부 스타일을 동적으로 전달할 수 있습니다.

<img
  className="avatar"
  style={{
    width: user.imageSize,
    height: user.imageSize
  }}
/>

위의 예시에서 style={{}}은 특별한 구문이 아니라 style={ }와 같이 중괄호가 있는 JSX 내에 있는 일반 {} 객체입니다. 스타일이 자바스크립트 변수에 의존하는 경우에만 style 어트리뷰트를 사용하는 것이 좋습니다.

export default function Avatar({ user }) {
  return (
    <img
      src={user.imageUrl}
      alt={'Photo of ' + user.name}
      className="avatar"
      style={{
        width: user.imageSize,
        height: user.imageSize
      }}
    />
  );
}
Deep Dive

여러 CSS 클래스를 조건부로 적용하기 위해 어떻게 해야하나요?

조건부로 CSS 클래스를 적용하려면 JavaScript를 사용하여 className 직접 문자열을 생성해야 합니다.

예를 들어 className={'row ' + (isSelected ? 'selected': '')}는 isSelected가 true인지의 여부에 따라 className="row" 또는 className="row selected"를 생성합니다.

가독성을 높이고 싶다면 classnames와 같은 작은 헬퍼 라이브러리를 사용할 수 있습니다.

import cn from 'classnames';

function Row({ isSelected }) {
  return (
    <div className={cn('row', isSelected && 'selected')}>
      ...
    </div>
  );
}

이는 조건부 클래스가 여러 개 있는 경우 특히 편리합니다.

import cn from 'classnames';

function Row({ isSelected, size }) {
  return (
    <div className={cn('row', {
      selected: isSelected,
      large: size === 'large',
      small: size === 'small',
    })}>
      ...
    </div>
  );
}

ref를 사용하여 DOM 노드 조작하기

때로는 JSX에서 태그와 연결된 브라우저 DOM 노드를 가져와야 하는 경우가 있습니다. 예를 들어 버튼이 클릭 될 때 <input> 에 포커싱을 맞추려면 브라우저의 <input> DOM 노드에서 focus()를 호출하면 됩니다.

태그에 대한 브라우저의 DOM 노드를 가져오려면 ref를 선언하고 해당 태그에 ref 어트리뷰트로 전달합니다.

import { useRef } from 'react';

export default function Form() {
  const inputRef = useRef(null);
  // ...
  return (
    <input ref={inputRef} />
    // ...

React는 DOM 노드가 화면에 렌더링 된 후 inputRef.current 에 넣습니다.

import { useRef } from 'react';

export default function Form() {
  const inputRef = useRef(null);

  function handleClick() {
    inputRef.current.focus();
  }

  return (
    <>
      <input ref={inputRef} />
      <button onClick={handleClick}>
        Focus the input
      </button>
    </>
  );
}

refs를 사용한 DOM 조작하기 및 더 많은 예제에 대해 더 자세히 읽어보세요.

고급 사용 사례의 경우 ref 어트리뷰트는 콜백 함수도 허용합니다.

내부 HTML을 위험하게 설정하는 경우

다음과 같이 원시 HTML 문자열을 엘리먼트에 전달할 수 있습니다.

const markup = { __html: '<p>some raw html</p>' };
return <div dangerouslySetInnerHTML={markup} />;

이것은 위험합니다. 기본 DOM의 innerHTML 프로퍼티와 마찬가지로 각별히 주의해야 합니다. 마크업이 완전히 신뢰할 수 있는 출처에서 제공되는 것이 아니라면, XSS 취약점이 쉽게 나타날 수 있습니다.

예를 들어, 마크다운을 HTML로 변환하는 라이브러리를 사용할 때, 해당 파서에 버그가 없고 사용자가 자신의 입력만 볼 수 있다고 믿는다면 다음과 같이 결과 HTML을 표시할 수 있습니다.

import { Remarkable } from 'remarkable';

const md = new Remarkable();

function renderMarkdownToHTML(markdown) {
  // 출력되는 HTML이 동일한 사용자에게 표시되고,
  // 이 마크다운 파서에 버그가 없다고 
  // 신뢰하기 때문에 안전합니다.
  const renderedHTML = md.render(markdown);
  return {__html: renderedHTML};
}

export default function MarkdownPreview({ markdown }) {
  const markup = renderMarkdownToHTML(markdown);
  return <div dangerouslySetInnerHTML={markup} />;
}

임의의 HTML을 렌더링하는 것이 왜 위험한지를 알아보려면 위의 코드를 다음과 같이 바꿔보세요.

const post = {
  // 이 content가 데이터베이스에 저장되어 있다고 가정해보겠습니다.
  content: `<img src="" onerror='alert("you were hacked")'>`
};

export default function MarkdownPreview() {
  // 🔴 보안 취약점: 신뢰할 수 없는 입력을 dangerouslySetInnerHTML로 전달했습니다.
  const markup = { __html: post.content };
  return <div dangerouslySetInnerHTML={markup} />;
}

HTML에 포함된 코드가 실행됩니다. 해커는 이 보안 허점을 이용하여 사용자의 정보를 훔치거나 사용자 대신 작업을 수행할 수 있습니다. 신뢰할 수 있고 유해한 정보가 포함되어 있지 않은 데이터를 사용할 때만 dangerouslySetInnerHTML을 사용하세요.

마우스 이벤트 처리

이 예시는 일반적인 마우스 이벤트와 해당 이벤트가 언제 발생하는지 보여줍니다.

export default function MouseExample() {
  return (
    <div
      onMouseEnter={e => console.log('onMouseEnter (parent)')}
      onMouseLeave={e => console.log('onMouseLeave (parent)')}
    >
      <button
        onClick={e => console.log('onClick (first button)')}
        onMouseDown={e => console.log('onMouseDown (first button)')}
        onMouseEnter={e => console.log('onMouseEnter (first button)')}
        onMouseLeave={e => console.log('onMouseLeave (first button)')}
        onMouseOver={e => console.log('onMouseOver (first button)')}
        onMouseUp={e => console.log('onMouseUp (first button)')}
      >
        First button
      </button>
      <button
        onClick={e => console.log('onClick (second button)')}
        onMouseDown={e => console.log('onMouseDown (second button)')}
        onMouseEnter={e => console.log('onMouseEnter (second button)')}
        onMouseLeave={e => console.log('onMouseLeave (second button)')}
        onMouseOver={e => console.log('onMouseOver (second button)')}
        onMouseUp={e => console.log('onMouseUp (second button)')}
      >
        Second button
      </button>
    </div>
  );
}

포인터 이벤트 처리

이 예시는 일반적인 포인터 이벤트와 해당 이벤트가 언제 발생하는지 보여줍니다.

export default function PointerExample() {
  return (
    <div
      onPointerEnter={e => console.log('onPointerEnter (parent)')}
      onPointerLeave={e => console.log('onPointerLeave (parent)')}
      style={{ padding: 20, backgroundColor: '#ddd' }}
    >
      <div
        onPointerDown={e => console.log('onPointerDown (first child)')}
        onPointerEnter={e => console.log('onPointerEnter (first child)')}
        onPointerLeave={e => console.log('onPointerLeave (first child)')}
        onPointerMove={e => console.log('onPointerMove (first child)')}
        onPointerUp={e => console.log('onPointerUp (first child)')}
        style={{ padding: 20, backgroundColor: 'lightyellow' }}
      >
        First child
      </div>
      <div
        onPointerDown={e => console.log('onPointerDown (second child)')}
        onPointerEnter={e => console.log('onPointerEnter (second child)')}
        onPointerLeave={e => console.log('onPointerLeave (second child)')}
        onPointerMove={e => console.log('onPointerMove (second child)')}
        onPointerUp={e => console.log('onPointerUp (second child)')}
        style={{ padding: 20, backgroundColor: 'lightblue' }}
      >
        Second child
      </div>
    </div>
  );
}

포커스 이벤트 처리

React에서는 focus 이벤트가 버블링됩니다. 부모 엘리먼트의 바깥 부분에서 발생한 이벤트가 focus 혹은 blur인지 구분하기 위해 currentTarget과 relatedTarget를 사용할 수 있습니다.

export default function FocusExample() {
  return (
    <div
      tabIndex={1}
      onFocus={(e) => {
        if (e.currentTarget === e.target) {
          console.log('focused parent');
        } else {
          console.log('focused child', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // children간의 focus를 이동할 때는 발생되지 않음.
          console.log('focus entered parent');
        }
      }}
      onBlur={(e) => {
        if (e.currentTarget === e.target) {
          console.log('unfocused parent');
        } else {
          console.log('unfocused child', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // children간의 focus를 이동할 때는 발생되지 않음.
          console.log('focus left parent');
        }
      }}
    >
      <label>
        First name:
        <input name="firstName" />
      </label>
      <label>
        Last name:
        <input name="lastName" />
      </label>
    </div>
  );
}

키보드 이벤트 처리

이 예시는 일반적인 키보드 이벤트와 해당 이벤트가 언제 발생하는지 보여줍니다.

export default function KeyboardExample() {
  return (
    <label>
      First name:
      <input
        name="firstName"
        onKeyDown={e => console.log('onKeyDown:', e.key, e.code)}
        onKeyUp={e => console.log('onKeyUp:', e.key, e.code)}
      />
    </label>
  );
}
이전컴포넌트다음<input>

이 문서가 마음에 드시나요?