In modern web development HTML will often be generated by various templating engines or compiled JavaScript syntax extensions. You should still try your best to build a DOM that is as semantic as possible to be search-engine friendly, accessible, and easily readable.

Semantic HTML

HTML5 introduced a number of new structural tags like section and article that are important to understand in order to use correctly (HTML5 Doctor is a great resource for this), but even fundamentally basic tags like small, ul, and li should be used intelligently. For example, a series of links in a site nav is semantically a "list," and should be either a ul or an ol depending upon whether the order of the links is meaningful.


Consider this variable declaration:

const element = <h1>Hello, world!</h1>;

The above syntax is neither a string nor HTML. It is called JSX, and it is a syntax extension to JavaScript. We recommend using it with React to describe what the UI should look like. JSX may remind you of a template language, but it comes with the full power of JavaScript.

User-Defined Components Must Be Capitalized

When an element type starts with a lowercase letter, it refers to a built-in component like <div> or <span> and results in a string 'div' or 'span' passed to React.createElement. Types that start with a capital letter like <Foo /> compile to React.createElement(Foo) and correspond to a component defined or imported in your JavaScript file.

We recommend naming components with a capital letter. If you do have a component that starts with a lowercase letter, assign it to a capitalized variable before using it in JSX.

Props Default to “True”

If you pass no value for a prop, it defaults to true. These two JSX expressions are equivalent:

<MyTextBox autocomplete />

<MyTextBox autocomplete={true} />

In order to stay in line with Airbnb Eslint rules, we recommend the shorthand version of passing true as props i.e. <MyTextBox autocomplete />.

Common Gotchas in JSX vs HTML

ARIA and accessibility

TODO: ARIA best practices
TODO: Considerations like tabindex and tag/component order