Semantic Jsx

title: "Semantic HTML in JSX" weight: 12 description: "Learn how to use semantic HTML elements in JSX, avoid common React anti-patterns like div soup and incorrect nesting, and ensure proper heading hierarchy and landmark structure in React components." date: 2026-06-28 lastmod: 2026-06-28 tags: [accessibility, react]

Semantic HTML in JSX means choosing the correct HTML element for each purpose -- nav for navigation, button for actions, h1-h6 for headings -- rather than using divs with ARIA roles, ensuring accessibility is built into React components from the start.

## What You'll Learn

You will use semantic HTML in JSX, avoid unnecessary div wrappers, maintain correct heading hierarchy, and use React Fragment for grouping without extra DOM nodes.

## Why It Matters

Semantic HTML provides accessibility for free. Screen readers and assistive technologies understand nav, main, button, and heading elements natively. Replacing them with divs and ARIA roles increases code complexity and introduces failure points.

## Real-World Use

A React app renders all navigation as divs with onClick handlers. A screen reader user cannot find the navigation landmarks. Refactoring to nav and button elements immediately makes the app navigable by screen reader.

## Semantic HTML Decisions

```mermaid
flowchart TD
  A[JSX Element] --> B{What is it?}
  B -->|Navigation| C[<nav>]
  B -->|Button action| D[<button>]
  B -->|Link to page| E[<a>]
  B -->|Heading| F[<h1-h6>]
  B -->|Generic container| G[<div> or <span>]
  B -->|Grouping without div| H[<Fragment>]

Using Semantic HTML

Replace div-based components with semantic alternatives.

// Bad: div-based navigation
function Nav() {
  return (
    <div className="navigation">
      <div className="nav-item" onClick={() => navigate('/')}>Home</div>
      <div className="nav-item" onClick={() => navigate('/about')}>About</div>
    </div>
  );
}

// Good: semantic navigation
function Nav() {
  return (
    <nav aria-label="Main navigation">
      <a href="/">Home</a>
      <a href="/about">About</a>
    </nav>
  );
}

// Bad: div button
function SubmitButton({ onClick }) {
  return (
    <div className="button" onClick={onClick} role="button" tabIndex={0}>
      Submit
    </div>
  );
}

// Good: button element
function SubmitButton({ onClick }) {
  return <button onClick={onClick}>Submit</button>;
}

// Using Fragment to avoid unnecessary divs
function ProductList({ products }) {
  return (
    <>
      <h2>Products</h2>
      {products.map(p => (
        <article key={p.id}>
          <h3>{p.name}</h3>
          <p>{p.price}</p>
        </article>
      ))}
    </>
  );
}

// Correct heading hierarchy
function Page() {
  return (
    <main>
      <h1>Page Title</h1>
      <section>
        <h2>Section</h2>
        <article>
          <h3>Article Title</h3>
        </article>
      </section>
    </main>
  );
}

Common Mistakes

• Using divs for buttons and links
• Nesting headings incorrectly or skipping levels
• Wrapping everything in unnecessary divs
• Using onClick on divs without keyboard support
• Not using main, nav, aside landmarks
• Breaking heading hierarchy with component abstraction
• Using role="button" on div instead of button element

Practice and Challenge

Practice 1: Find and fix three div-based buttons in a React component. Practice 2: Replace a div-based navigation with nav and a elements. Practice 3: Check heading hierarchy in a complex React page. Practice 4: Replace unnecessary div wrappers with Fragments. Practice 5: Add landmark elements (main, nav, aside) to a React page.

Challenge: Refactor a React component that uses divs for everything (buttons, links, navigation, card containers) to use semantic HTML elements. The component should use button, a, nav, article, main, heading, and aside elements correctly. Verify that the component works the same visually but is now accessible with screen readers.

FAQ

Mini Project

Create a React page template using semantic HTML: header with nav, main content with article and aside sections, and footer. The template should use proper heading hierarchy (h1 for page title, h2 for sections, h3 for sub-sections) and include landmarks (main, nav, aside, header, footer).

What's Next

ARIA Attributes in JSX covers applying ARIA attributes in React components.