Komponen umum (e.g. <div>)

Semua komponen bawaan dari sebuah peramban web (browser), seperti <div>, mendukung beberapa props umum dan event.


Referensi

Komponen umum (e.g. <div>)

<div className="wrapper">beberapa konten</div>

See more examples below.

Props

Beberapa props spesial React berikut didukung oleh setiap komponen bawaan:

  • children: Sebuah node React (sebuah elemen, string, angka, portal, node kosong seperti null, undefined and booleans, atau senarai dari nodes React). Menggambarkan kontent yang berada di dalam komponen. Saat menggunakan JSX, biasanya kau akan mendefinisikan prop dari children secara implisit dengan menggunakan tag bersarang seperti <div><span /></div>.

  • dangerouslySetInnerHTML: Sebuah objek dengan bentuk { __html: '<p>some html</p>' } yang mengandung string HTML mentah. Objek ini menimpa innerHTML yang merupakan properti dari DOM node dan menampilkan HTML yang di-passing ke dalamnya. Hal ini harus digunakan dengan sangat hati-hati! Jika HTML yang berada didalamnya tidak terpercaya (sebagai contoh, jika datanya berbasis pada data pengguna), akan beresiko pada munculnya kerentanan terhadap XSS. Baca lebih lanjut mengenai penggunaan dangerouslySetInnerHTML.

  • ref: Ref adalah sebuah objek dari useRef atau createRef, atau sebuah fungsi callback ref, atau sebuah string untuk legacy refs. Ref anda akan diisi dengan elemen DOM untuk node tersebut. Baca lebih lanjut mengenai memanipulasi DOM dengan refs.

  • suppressContentEditableWarning: Sebuah boolean. Jika true, menekan peringatan yang ditampilkan oleh React untuk element yang memngandung children dan contentEditable={true} (yang biasanya tidak bekerja secara bersamaan). Gunakan prop ini jika anda sedang membangun sebuah library input teks yang mengelola konten contentEditable secara manual.

  • suppressHydrationWarning: Sebuah boolean. Jika anda menggunakan server rendering, biasanya terdapat peringatan saat server dan client me-render konten yang berbeda. Untuk beberapa kasus langka (seperti tag waktu), sangat sulit atau tidak mungkin untuk menjamin kecocokan yang tepat. Jika anda mengatur suppressHydrationWarning menjadi true, React tidak akan memperingati anda mengenai ketidakcocokan dalam atribut ataupun konten dari elemen tersebut. Ini hanya bekerja sedalam satu tingkat, dan dimaksudkan untuk digunakan sebagai pintu keluar darurat. Jangan terlalu sering menggunakannya. Baca mengenai menekan kesalahan hidrasi.

  • style: Sebuah objek styles CSS, sebagai contoh { fontWeight: 'bold', margin: 20 }. Seperti properti dari DOM style, penamaan dari properti CSS harus ditulis dalam camelCase, sebagai contoh fontWeight bukan font-weight. Anda dapat memasukkan string atau angka sebagai nilai. Jika anda memasukkan angka, seperti width: 100, React akan secara otomatis menambahkan px (“piksel”) ke dalam nilai tersebut kecuali jika properti tersebut merupakan properti tanpa unit. Kami merekomendasikan penggunaan style hanya untuk styles yang bersifat dinamis yang mana nilai dari style tersebut masih dapat berubah-ubah. Untuk kasus lainnya, penggunaan kelas CSS biasa dengan className lebih efisien. Baca lebih lanjut mengenai className dan style.

Berikut props DOM standar yang juga didukung oleh setiap komponen bawaan:

You can also pass custom attributes as props, for example mycustomprop="someValue". This can be useful when integrating with third-party libraries. The custom attribute name must be lowercase and must not start with on. The value will be converted to a string. If you pass null or undefined, the custom attribute will be removed.

These events fire only for the <form> elements:

These events fire only for the <dialog> elements. Unlike browser events, they bubble in React:

These events fire only for the <details> elements. Unlike browser events, they bubble in React:

These events fire for <img>, <iframe>, <object>, <embed>, <link>, and SVG <image> elements. Unlike browser events, they bubble in React:

These events fire for resources like <audio> and <video>. Unlike browser events, they bubble in React:

Caveats

  • You cannot pass both children and dangerouslySetInnerHTML at the same time.
  • Some events (like onAbort and onLoad) don’t bubble in the browser, but bubble in React.

ref callback function

Instead of a ref object (like the one returned by useRef), you may pass a function to the ref attribute.

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

See an example of using the ref callback.

When the <div> DOM node is added to the screen, React will call your ref callback with the DOM node as the argument. When that <div> DOM node is removed, React will call your ref callback with null.

React will also call your ref callback whenever you pass a different ref callback. In the above example, (node) => { ... } is a different function on every render. When your component re-renders, the previous function will be called with null as the argument, and the next function will be called with the DOM node.

Parameters

  • node: A DOM node or null. React will pass you the DOM node when the ref gets attached, and null when the ref gets detached. Unless you pass the same function reference for the ref callback on every render, the callback will get temporarily detached and re-attached during ever re-render of the component.

Returns

Do not return anything from the ref callback.


React event object

Your event handlers will receive a React event object. It is also sometimes known as a “synthetic event”.

<button onClick={e => {
console.log(e); // React event object
}} />

It conforms to the same standard as the underlying DOM events, but fixes some browser inconsistencies.

Some React events do not map directly to the browser’s native events. For example in onMouseLeave, e.nativeEvent will point to a mouseout event. The specific mapping is not part of the public API and may change in the future. If you need the underlying browser event for some reason, read it from e.nativeEvent.

Properties

React event objects implement some of the standard Event properties:

  • bubbles: A boolean. Returns whether the event bubbles through the DOM.
  • cancelable: A boolean. Returns whether the event can be canceled.
  • currentTarget: A DOM node. Returns the node to which the current handler is attached in the React tree.
  • defaultPrevented: A boolean. Returns whether preventDefault was called.
  • eventPhase: A number. Returns which phase the event is currently in.
  • isTrusted: A boolean. Returns whether the event was initiated by user.
  • target: A DOM node. Returns the node on which the event has occurred (which could be a distant child).
  • timeStamp: A number. Returns the time when the event occurred.

Additionally, React event objects provide these properties:

  • nativeEvent: A DOM Event. The original browser event object.

Methods

React event objects implement some of the standard Event methods:

Additionally, React event objects provide these methods:

  • isDefaultPrevented(): Returns a boolean value indicating whether preventDefault was called.
  • isPropagationStopped(): Returns a boolean value indicating whether stopPropagation was called.
  • persist(): Not used with React DOM. With React Native, call this to read event’s properties after the event.
  • isPersistent(): Not used with React DOM. With React Native, returns whether persist has been called.

Caveats

  • The values of currentTarget, eventPhase, target, and type reflect the values your React code expects. Under the hood, React attaches event handlers at the root, but this is not reflected in React event objects. For example, e.currentTarget may not be the same as the underlying e.nativeEvent.currentTarget. For polyfilled events, e.type (React event type) may differ from e.nativeEvent.type (underlying type).

AnimationEvent handler function

An event handler type for the CSS animation events.

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

Parameters


ClipboardEvent handler function

An event handler type for the Clipboard API events.

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

Parameters


CompositionEvent handler function

An event handler type for the input method editor (IME) events.

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

Parameters


DragEvent handler function

An event handler type for the HTML Drag and Drop API events.

<>
<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>
</>

Parameters


FocusEvent handler function

An event handler type for the focus events.

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

See an example.

Parameters


Event handler function

An event handler type for generic events.

Parameters


InputEvent handler function

An event handler type for the onBeforeInput event.

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

Parameters


KeyboardEvent handler function

An event handler type for keyboard events.

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

See an example.

Parameters


MouseEvent handler function

An event handler type for mouse events.

<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')}
/>

See an example.

Parameters


PointerEvent handler function

An event handler type for pointer events.

<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')}
/>

See an example.

Parameters


TouchEvent handler function

An event handler type for touch events.

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

Parameters


TransitionEvent handler function

An event handler type for the CSS transition events.

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

Parameters


UIEvent handler function

An event handler type for generic UI events.

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

Parameters


WheelEvent handler function

An event handler type for the onWheel event.

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

Parameters


Usage

Applying CSS styles

In React, you specify a CSS class with className. It works like the class attribute in HTML:

<img className="avatar" />

Then you write the CSS rules for it in a separate CSS file:

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

React does not prescribe how you add CSS files. In the simplest case, you’ll add a <link> tag to your HTML. If you use a build tool or a framework, consult its documentation to learn how to add a CSS file to your project.

Sometimes, the style values depend on data. Use the style attribute to pass some styles dynamically:

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

In the above example, style={{}} is not a special syntax, but a regular {} object inside the style={ } JSX curly braces. We recommend only using the style attribute when your styles depend on JavaScript variables.

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

How to apply multiple CSS classes conditionally?

To apply CSS classes conditionally, you need to produce the className string yourself using JavaScript.

For example, className={'row ' + (isSelected ? 'selected': '')} will produce either className="row" or className="row selected" depending on whether isSelected is true.

To make this more readable, you can use a tiny helper library like classnames:

import cn from 'classnames';

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

It is especially convenient if you have multiple conditional classes:

import cn from 'classnames';

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

Manipulating a DOM node with a ref

Sometimes, you’ll need to get the browser DOM node associated with a tag in JSX. For example, if you want to focus an <input> when a button is clicked, you need to call focus() on the browser <input> DOM node.

To obtain the browser DOM node for a tag, declare a ref and pass it as the ref attribute to that tag:

import { useRef } from 'react';

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

React will put the DOM node into inputRef.current after it’s been rendered to the screen.

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>
    </>
  );
}

Read more about manipulating DOM with refs and check out more examples.

For more advanced use cases, the ref attribute also accepts a callback function.


Dangerously setting the inner HTML

You can pass a raw HTML string to an element like so:

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

This is dangerous. As with the underlying DOM innerHTML property, you must exercise extreme caution! Unless the markup is coming from a completely trusted source, it is trivial to introduce an XSS vulnerability this way.

For example, if you use a Markdown library that converts Markdown to HTML, you trust that its parser doesn’t contain bugs, and the user only sees their own input, you can display the resulting HTML like this:

import { Remarkable } from 'remarkable';

const md = new Remarkable();

function renderMarkdownToHTML(markdown) {
  // This is ONLY safe because the output HTML
  // is shown to the same user, and because you
  // trust this Markdown parser to not have bugs.
  const renderedHTML = md.render(markdown);
  return {__html: renderedHTML};
}

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

To see why rendering arbitrary HTML is dangerous, replace the code above with this:

const post = {
// Imagine this content is stored in the database.
content: `<img src="" onerror='alert("you were hacked")'>`
};

export default function MarkdownPreview() {
// 🔴 SECURITY HOLE: passing untrusted input to dangerouslySetInnerHTML
const markup = { __html: post.content };
return <div dangerouslySetInnerHTML={markup} />;
}

The code embedded in the HTML will run. A hacker could use this security hole to steal user information or to perform actions on their behalf. Only use dangerouslySetInnerHTML with trusted and sanitized data.


Handling mouse events

This example shows some common mouse events and when they fire.

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>
  );
}


Handling pointer events

This example shows some common pointer events and when they fire.

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>
  );
}


Handling focus events

In React, focus events bubble. You can use the currentTarget and relatedTarget to differentiate if the focusing or blurring events originated from outside of the parent element. The example shows how to detect focusing a child, focusing the parent element, and how to detect focus entering or leaving the whole subtree.

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)) {
          // Not triggered when swapping focus between children
          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)) {
          // Not triggered when swapping focus between children
          console.log('focus left parent');
        }
      }}
    >
      <label>
        First name:
        <input name="firstName" />
      </label>
      <label>
        Last name:
        <input name="lastName" />
      </label>
    </div>
  );
}


Handling keyboard events

This example shows some common keyboard events and when they fire.

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>
  );
}