Airbnb React/JSX Style Guide

A truly reasonable approach to React and JSX

This style guide is mostly based on the standards that are currently prevalent in JavaScript, although some conventions (i.e async/await or static class fields) may still be included or prohibited on a case-by-case basis. Currently, anything prior to stage 3 is not included nor recommended in this guide.

Basic Rules

Only include one React component per file.
- However, multiple Stateless, or Pure, Components are allowed per file. eslint: react/no-multi-comp.
Always use JSX syntax.
Do not use React.createElement unless you’re initializing the app from a file that is not JSX.
react/forbid-prop-types will allow arrays and objects only if it is explicitly noted what array and object contains, using arrayOf, objectOf, or shape.

Class vs `React.createClass` vs stateless

If you have internal state and/or refs, prefer class extends React.Component over React.createClass. eslint: react/prefer-es6-class react/prefer-stateless-function

// bad
const Listing = React.createClass({
  // ...
  render() {
    return <div>{this.state.hello}</div>;
  }
});

// good
class Listing extends React.Component {
  // ...
  render() {
    return <div>{this.state.hello}</div>;
  }
}

And if you don’t have state or refs, prefer normal functions (not arrow functions) over classes:

// bad
class Listing extends React.Component {
  render() {
    return <div>{this.props.hello}</div>;
  }
}

// bad (relying on function name inference is discouraged)
const Listing = ({ hello }) => (
  <div>{hello}</div>
);

// good
function Listing({ hello }) {
  return <div>{hello}</div>;
}

Mixins

Do not use mixins.

Why? Mixins introduce implicit dependencies, cause name clashes, and cause snowballing complexity. Most use cases for mixins can be accomplished in better ways via components, higher-order components, or utility modules.

Naming

Extensions: Use .jsx extension for React components. eslint: react/jsx-filename-extension
Filename: Use PascalCase for filenames. E.g., ReservationCard.jsx.

Reference Naming: Use PascalCase for React components and snake_case for their instances. eslint: react/jsx-pascal-case

// bad
import reservationCard from './ReservationCard';

// good
import ReservationCard from './ReservationCard';

// bad
const ReservationItem = <ReservationCard />;

// good
const reservation_item = <ReservationCard />;

Component Naming: Use the filename as the component name. For example, ReservationCard.jsx should have a reference name of ReservationCard. However, for root components of a directory, use index.jsx as the filename and use the directory name as the component name:
```
// bad
import Footer from './Footer/Footer';

// bad
import Footer from './Footer/index';

// good
import Footer from './Footer';
```

Higher-order Component Naming: Use a composite of the higher-order component’s name and the passed-in component’s name as the displayName on the generated component. For example, the higher-order component withFoo(), when passed a component Bar should produce a component with a displayName of withFoo(Bar).

Why? A component’s displayName may be used by developer tools or in error messages, and having a value that clearly expresses this relationship helps people understand what is happening.

// bad
export default function withFoo(WrappedComponent) {
  return function WithFoo(props) {
    return <WrappedComponent {...props} foo />;
  }
}

// good
export default function withFoo(WrappedComponent) {
  function WithFoo(props) {
    return <WrappedComponent {...props} foo />;
  }

  const wrappedComponentName = WrappedComponent.displayName
    || WrappedComponent.name
    || 'Component';

  WithFoo.displayName = `withFoo(${wrappedComponentName})`;
  return WithFoo;
}

Props Naming: Avoid using DOM component prop names for different purposes.

Why? People expect props like style and className to mean one specific thing. Varying this API for a subset of your app makes the code less readable and less maintainable, and may cause bugs.
```
// bad
<MyComponent style="fancy" />

// bad
<MyComponent className="fancy" />

// good
<MyComponent variant="fancy" />
```

Declaration

Do not use displayName for naming components. Instead, name the component by reference.

// bad
export default React.createClass({
  displayName: 'ReservationCard',
  // stuff goes here
});

// good
export default class ReservationCard extends React.Component {
}

Alignment

Follow these alignment styles for JSX syntax. eslint: react/jsx-closing-bracket-location react/jsx-closing-tag-location

// bad
<Foo superLongParam="bar"
     anotherSuperLongParam="baz" />

// good
<Foo
  superLongParam="bar"
  anotherSuperLongParam="baz"
/>

// if props fit in one line then keep it on the same line
<Foo bar="bar" />

// children get indented normally
<Foo superLongParam="bar" anotherSuperLongParam="baz">
  <Quux />
</Foo>

// bad
{showButton &&
  <Button />
}

// bad
{
  showButton &&
    <Button />
}

// bad
{showButton && (
  <Button />
)}

// good
{showButton && <Button />}

Quotes

Always use double quotes (") for JSX attributes, but single quotes (') for all other JS. eslint: jsx-quotes

Why? Regular HTML attributes also typically use double quotes instead of single, so JSX attributes mirror this convention.
```
// bad
<Foo bar='bar' />

// good
<Foo bar="bar" />

// bad
<Foo style={{ left: "20px" }} />

// good
<Foo style={{ left: '20px' }} />
```

Spacing

Always include a single space in your self-closing tag. eslint: no-multi-spaces, react/jsx-tag-spacing

// bad
<Foo/>

// very bad
<Foo                 />

// bad
<Foo
 />

// good
<Foo />

Do not pad JSX curly braces with spaces. eslint: react/jsx-curly-spacing
```
// bad
<Foo bar={ baz } />

// good
<Foo bar={baz} />
```

Props

Use camelCase for prop names whose value is callable, snake_case otherwise.

// bad
<Foo
  UserName="hello"
  PhoneNumber={12345678}
/>

// good
<Foo
  user_name="hello"
  phone_number={12345678}
  renderProp={someCallable}
/>

Omit the value of the prop when it is explicitly true. eslint: react/jsx-boolean-value

// bad
<Foo
  hidden={true}
/>

// good
<Foo
  hidden
/>

// good
<Foo hidden />

Always include an alt prop on <img> tags. If the image is presentational, alt can be an empty string or the <img> must have role="presentation". eslint: jsx-a11y/alt-text

// bad
<img src="hello.jpg" />

// good
<img src="hello.jpg" alt="Me waving hello" />

// good
<img src="hello.jpg" alt="" />

// good
<img src="hello.jpg" role="presentation" />

Do not use words like "image", "photo", or "picture" in <img> alt props. eslint: jsx-a11y/img-redundant-alt

Why? Screenreaders already announce img elements as images, so there is no need to include this information in the alt text.
```
// bad
<img src="hello.jpg" alt="Picture of me waving hello" />

// good
<img src="hello.jpg" alt="Me waving hello" />
```

Use only valid, non-abstract ARIA roles. eslint: jsx-a11y/aria-role

// bad - not an ARIA role
<div role="datepicker" />

// bad - abstract ARIA role
<div role="range" />

// good
<div role="button" />

Do not use accessKey on elements. eslint: jsx-a11y/no-access-key

Why? Inconsistencies between keyboard shortcuts and keyboard commands used by people using screenreaders and keyboards complicate accessibility.
```
// bad
<div accessKey="h" />

// good
<div />
```
Avoid using an array index as key prop, prefer a stable ID. eslint: react/no-array-index-key

Why? Not using a stable ID is an anti-pattern because it can negatively impact performance and cause issues with component state.

We don’t recommend using indexes for keys if the order of items may change.
```
// bad
{todos.map((todo, index) =>
  <Todo
    {...todo}
    key={index}
  />
)}

// good
{todos.map(todo => (
  <Todo
    {...todo}
    key={todo.id}
  />
))}
```

Always define explicit defaultProps for all non-required props.

Why? propTypes are a form of documentation, and providing defaultProps means the reader of your code doesn’t have to assume as much. In addition, it can mean that your code can omit certain type checks.

// bad
function SFC({ foo, bar, children }) {
  return <div>{foo}{bar}{children}</div>;
}
SFC.propTypes = {
  foo: PropTypes.number.isRequired,
  bar: PropTypes.string,
  children: PropTypes.node,
};

// good
function SFC({ foo, bar, children }) {
  return <div>{foo}{bar}{children}</div>;
}
SFC.propTypes = {
  foo: PropTypes.number.isRequired,
  bar: PropTypes.string,
  children: PropTypes.node,
};
SFC.defaultProps = {
  bar: '',
  children: null,
};

Use spread props sparingly.

Why? Otherwise you’re more likely to pass unnecessary props down to components.

Exceptions:

HOCs that proxy down props and hoist propTypes

function HOC(WrappedComponent) {
  return class Proxy extends React.Component {
    prop_types = {
      text: PropTypes.string,
      isLoading: PropTypes.bool
    };

    render() {
      return <WrappedComponent {...this.props} />
    }
  }
}

Spreading objects with known, explicit props. This can be particularly useful when testing React components with Mocha’s beforeEach construct.

export default function Foo() {
  const props = {
    text: '',
    isPublished: false
  }

  return (<div {...props} />);
}

Notes for use: Filter out unnecessary props when possible. Also, use prop-types-exact to help prevent bugs.

// bad
render() {
  return <WrappedComponent {...this.props} />
}

// good
render() {
  const { irrelevantProp, ...relevantProps } = this.props;
  return <WrappedComponent {...relevantProps} />
}

Refs

Always use ref callbacks. eslint: react/no-string-refs

// bad
<Foo
  ref="myRef"
/>

// good
<Foo
  ref={ref => this.myRef = ref}
/>

Parentheses

Wrap JSX tags in parentheses when they span more than one line. eslint: react/jsx-wrap-multilines

// bad
render() {
  return <MyComponent variant="long body" foo="bar">
           <MyChild />
         </MyComponent>;
}

// good
render() {
  return (
    <MyComponent variant="long body" foo="bar">
      <MyChild />
    </MyComponent>
  );
}

// good, when single line
render() {
  const body = <div>hello</div>;
  return <MyComponent>{body}</MyComponent>;
}

Methods

Use arrow functions in class fields instead of binding methods in the constructor. eslint: react/jsx-no-bind

Why? Clean code.

// bad
class SomeComponent extends React.Component {
  onClickDiv() {
    // do stuff
  }

  render() {
    return <div onClick={this.onClickDiv.bind(this)} />;
  }
}

// okay
class SomeComponent extends React.Component {
  constructor(props) {
    super(props);

    this.onClickDiv = this.onClickDiv.bind(this);
  }

  onClickDiv() {
    // do stuff
  }

  render() {
    return <div onClick={this.onClickDiv} />;
  }
}

// good
class SomeComponent extends React.Component {
  onClickDiv = () => {
    // do stuff
  };

  render() {
    return <div onClick={this.onClickDiv} />
  }
}

Use underscore prefix for internal methods of a React component.

Why? A leading underscore is a common convention to signify that a property or method is not intended to be used from outside a class instance. It makes comprehending the code easier and faster.
```
// bad
React.createClass({
  onClickSubmit() {
    // do stuff
  },

  // other stuff
});

// good
class SomeComponent extends React.Component {
  _onClickSubmit() {
    // do stuff
  }

  // other stuff
}
```

Be sure to return a value in your render methods. eslint: react/require-render-return

// bad
render() {
  (<div />);
}

// good
render() {
  return <div />;
}

Ordering

Ordering for class extends React.Component:

private class fields
public class fields
constructor
internal methods like _processSomething() or _makeAJAXRequest()
componentWillMount
componentDidMount
componentWillReceiveProps
shouldComponentUpdate
componentWillUpdate
componentDidUpdate
componentWillUnmount
clickHandlers or eventHandlers like onClickSubmit() or onChangeDescription()
optional render methods like _renderNavigation() or _renderProfilePicture()
render

How to define propTypes, defaultProps, contextTypes, etc...

import React from 'react';
import PropTypes from 'prop-types';

class Link extends React.Component {
  default_props = {
    text: 'Hello World',
  };

  propTypes = {
    id: PropTypes.number.isRequired,
    url: PropTypes.string.isRequired,
    text: PropTypes.string,
  };

  render() {
    return <a href={this.props.url} data-id={this.props.id}>{this.props.text}</a>;
  }
}

export default Link;

Translation

This JSX/React style guide is also available in other languages:

⬆ back to top

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Airbnb React/JSX Style Guide

Table of Contents

Basic Rules

Class vs `React.createClass` vs stateless

Mixins

Naming

Declaration

Alignment

Quotes

Spacing

Props

Refs

Parentheses

Tags

Methods

Ordering

Translation

Files

README.md

Latest commit

History

README.md

File metadata and controls

Airbnb React/JSX Style Guide

Table of Contents

Basic Rules

Class vs React.createClass vs stateless

Mixins

Naming

Declaration

Alignment

Quotes

Spacing

Props

Refs

Parentheses

Tags

Methods

Ordering

Translation

Class vs `React.createClass` vs stateless