react

Airbnb React/JSX Style Guide

A mostly 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.

Table of Contents

1. Basic Rules
2. Class vs React.createClass vs stateless
3. Mixins
4. Naming
5. Declaration
6. Alignment
7. Quotes
8. Spacing
9. Props
10. Refs
11. Parentheses
12. Tags
13. Methods
14. Ordering
15. isMounted

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.

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-classreact/prefer-stateless-function

  // badconstListing=React.createClass({// ...render(){return<div>{this.state.hello}</div>;}});// goodclassListingextendsReact.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:

  // badclassListingextendsReact.Component{render(){return<div>{this.props.hello}</div>;}}// bad (relying on function name inference is discouraged)constListing=({ hello })=>(<div>{hello}</div>);// goodfunctionListing({ 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.

• Filename: Use PascalCase for filenames. E.g., ReservationCard.jsx.

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

  // badimportreservationCardfrom'./ReservationCard';// goodimportReservationCardfrom'./ReservationCard';// badconstReservationItem=<ReservationCard/>;// goodconstreservationItem=<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:

  // badimportFooterfrom'./Footer/Footer';// badimportFooterfrom'./Footer/index';// goodimportFooterfrom'./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.

  // badexportdefaultfunctionwithFoo(WrappedComponent){returnfunctionWithFoo(props){return<WrappedComponent{...props}foo/>;}}// goodexportdefaultfunctionwithFoo(WrappedComponent){functionWithFoo(props){return<WrappedComponent{...props}foo/>;}constwrappedComponentName=WrappedComponent.displayName||WrappedComponent.name||'Component';WithFoo.displayName=`withFoo(${wrappedComponentName})`;returnWithFoo;}

• 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<MyComponentstyle="fancy"/>// bad<MyComponentclassName="fancy"/>// good<MyComponentvariant="fancy"/>

Declaration

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

  // badexportdefaultReact.createClass({displayName: 'ReservationCard',// stuff goes here});// goodexportdefaultclassReservationCardextendsReact.Component{}

Alignment

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

  // bad<FoosuperLongParam="bar"anotherSuperLongParam="baz"/>// good<FoosuperLongParam="bar"anotherSuperLongParam="baz"/>// if props fit in one line then keep it on the same line<Foobar="bar"/>// children get indented normally<FoosuperLongParam="bar"anotherSuperLongParam="baz"><Quux/></Foo>// bad{showButton&&<Button/>}// bad{showButton&&<Button/>}// good{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<Foobar='bar'/>// good<Foobar="bar"/>// bad<Foostyle={{left: "20px"}}/>// good<Foostyle={{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<Foobar={baz}/>// good<Foobar={baz}/>

Props

• Always use camelCase for prop names.

  // bad<FooUserName="hello"phone_number={12345678}/>// good<FoouserName="hello"phoneNumber={12345678}/>

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

  // bad<Foohidden={true}/>// good<Foohidden/>// good<Foohidden/>

• 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<imgsrc="hello.jpg"/>// good<imgsrc="hello.jpg"alt="Me waving hello"/>// good<imgsrc="hello.jpg"alt=""/>// good<imgsrc="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<imgsrc="hello.jpg"alt="Picture of me waving hello"/>// good<imgsrc="hello.jpg"alt="Me waving hello"/>

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

  // bad - not an ARIA role<divrole="datepicker"/>// bad - abstract ARIA role<divrole="range"/>// good<divrole="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<divaccessKey="h"/>// good<div/>

• Avoid using an array index as key prop, prefer a stable ID.

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.

// badfunctionSFC({ foo, bar, children }){return<div>{foo}{bar}{children}</div>;}SFC.propTypes={foo: PropTypes.number.isRequired,bar: PropTypes.string,children: PropTypes.node,};// goodfunctionSFC({ 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. And for React v15.6.1 and older, you could pass invalid HTML attributes to the DOM.

Exceptions:

• HOCs that proxy down props and hoist propTypes

functionHOC(WrappedComponent){returnclassProxyextendsReact.Component{Proxy.propTypes={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.

exportdefaultfunctionFoo{constprops={text: '',isPublished: false}return(<div{...props}/>);}

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

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

Refs

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

  // bad<Fooref="myRef"/>// good<Fooref={(ref)=>{this.myRef=ref;}}/>

Parentheses

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

  // badrender(){return<MyComponentvariant="long body"foo="bar"><MyChild/></MyComponent>;}// goodrender(){return(<MyComponentvariant="long body"foo="bar"><MyChild/></MyComponent>);}// good, when single linerender(){constbody=<div>hello</div>;return<MyComponent>{body}</MyComponent>;}

Tags

• Always self-close tags that have no children. eslint: react/self-closing-comp

  // bad<Foovariant="stuff"></Foo>// good<Foovariant="stuff"/>

• If your component has multi-line properties, close its tag on a new line. eslint: react/jsx-closing-bracket-location

  // bad<Foobar="bar"baz="baz"/>// good<Foobar="bar"baz="baz"/>

Methods

• Use arrow functions to close over local variables.

  functionItemList(props){return(<ul>{props.items.map((item,index)=>(<Itemkey={item.key}onClick={()=>doSomethingWith(item.name,index)}/>))}</ul>);}

• Bind event handlers for the render method in the constructor. eslint: react/jsx-no-bind

  Why? A bind call in the render path creates a brand new function on every single render.

  // badclassextendsReact.Component{onClickDiv(){// do stuff}render(){return<divonClick={this.onClickDiv.bind(this)}/>;}}// goodclassextendsReact.Component{constructor(props){super(props);this.onClickDiv=this.onClickDiv.bind(this);}onClickDiv(){// do stuff}render(){return<divonClick={this.onClickDiv}/>;}}

• Do not use underscore prefix for internal methods of a React component.

  Why? Underscore prefixes are sometimes used as a convention in other languages to denote privacy. But, unlike those languages, there is no native support for privacy in JavaScript, everything is public. Regardless of your intentions, adding underscore prefixes to your properties does not actually make them private, and any property (underscore-prefixed or not) should be treated as being public. See issues #1024, and #490 for a more in-depth discussion.

  // badReact.createClass({_onClickSubmit(){// do stuff},// other stuff});// goodclassextendsReact.Component{onClickSubmit(){// do stuff}// other stuff}

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

  // badrender(){(<div/>);}// goodrender(){return(<div/>);}

Ordering

• Ordering for class extends React.Component:

1. optional static methods
2. constructor
3. getChildContext
4. componentWillMount
5. componentDidMount
6. componentWillReceiveProps
7. shouldComponentUpdate
8. componentWillUpdate
9. componentDidUpdate
10. componentWillUnmount
11. clickHandlers or eventHandlers like onClickSubmit() or onChangeDescription()
12. getter methods for render like getSelectReason() or getFooterContent()
13. optional render methods like renderNavigation() or renderProfilePicture()
14. render

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

  importReactfrom'react';importPropTypesfrom'prop-types';constpropTypes={id: PropTypes.number.isRequired,url: PropTypes.string.isRequired,text: PropTypes.string,};constdefaultProps={text: 'Hello World',};classLinkextendsReact.Component{staticmethodsAreOk(){returntrue;}render(){return<ahref={this.props.url}data-id={this.props.id}>{this.props.text}</a>;}}Link.propTypes=propTypes;Link.defaultProps=defaultProps;exportdefaultLink;

• Ordering for React.createClass: eslint: react/sort-comp

1. displayName
2. propTypes
3. contextTypes
4. childContextTypes
5. mixins
6. statics
7. defaultProps
8. getDefaultProps
9. getInitialState
10. getChildContext
11. componentWillMount
12. componentDidMount
13. componentWillReceiveProps
14. shouldComponentUpdate
15. componentWillUpdate
16. componentDidUpdate
17. componentWillUnmount
18. clickHandlers or eventHandlers like onClickSubmit() or onChangeDescription()
19. getter methods for render like getSelectReason() or getFooterContent()
20. optional render methods like renderNavigation() or renderProfilePicture()
21. render

isMounted

• Do not use isMounted. eslint: react/no-is-mounted

Why? isMounted is an anti-pattern, is not available when using ES6 classes, and is on its way to being officially deprecated.

Translation

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

• Chinese (Simplified): JasonBoy/javascript
• Chinese (Traditional): jigsawye/javascript
• Español: agrcrobles/javascript
• Japanese: mitsuruog/javascript-style-guide
• Korean: apple77y/javascript
• Polish: pietraszekl/javascript
• Portuguese: ronal2do/javascript
• Russian: leonidlebedev/javascript-airbnb
• Thai: lvarayut/javascript-style-guide
• Turkish: alioguzhan/react-style-guide
• Ukrainian: ivanzusko/javascript
• Vietnam: uetcodecamp/jsx-style-guide

⬆ back to top