Skip to content

React Best Practices

Project structure, naming conventions, accessibility, and clean code principles for React.

What you'll learn

  • Organizing files and folders for scalability
  • Naming conventions and component patterns
  • Accessibility as a first-class concern
  • Code quality: linting, formatting, and code review

Concept

Project Structure

A good project structure scales with your team and codebase. A common approach is feature-based organization: group files by feature or domain (e.g., features/auth/, features/dashboard/) rather than by file type (components/, hooks/, utils/). Each feature folder contains its components, hooks, tests, and types. Shared code goes in a shared/ or lib/ directory. This makes it easy to find all code related to a feature and to move or delete a feature without touching unrelated files. Keep the structure flat enough to navigate but organized enough to scale.

Naming Conventions

Consistent naming is crucial for readability. Components use PascalCase: UserProfile, SearchBar. Hooks start with use: useAuth, useDebounce. Event handlers start with handle: handleSubmit, handleClick. Props that are callbacks use on prefix: onSubmit, onChange. Boolean props use is/has/should: isLoading, hasError, shouldRender. Files match their default export: UserProfile.tsx exports UserProfile. Consistency matters more than the specific convention — pick one and enforce it with linting.

Accessibility

Accessibility (a11y) is not optional — it is a legal requirement and a moral imperative. Use semantic HTML: <button> for clickable actions (not <div onClick>), <nav> for navigation, <main> for main content, <header> and <footer> for their respective areas. Provide alt text for images, aria-label for icon-only buttons, and label elements for form inputs. Manage focus for keyboard users (tab order, focus trapping in modals). Test with a screen reader and keyboard-only navigation. Libraries like react-aria and @radix-ui provide accessible primitives.

Code Quality

Enforce code quality with tooling. ESLint with eslint-plugin-react and eslint-plugin-react-hooks catches common mistakes (missing deps in useEffect, hook rule violations). Prettier formats code consistently. TypeScript provides type safety. Write tests for critical user flows. Review code for readability — code is read far more often than it is written. Keep components small and focused, extract reusable logic into custom hooks, and prefer composition over inheritance. Document complex logic with comments, but let clear naming and structure do most of the documentation work.

Example

              // Good: semantic HTML, accessible labels, clear naming.
function SearchBar({ onSearch, isLoading }) {
  const [query, setQuery] = useState("");

  const handleSubmit = (e) => {
    e.preventDefault();
    if (query.trim()) onSearch(query.trim());
  };

  return (
    <form onSubmit={handleSubmit} role="search">
      <label htmlFor="search-input" className="sr-only">Search</label>
      <input
        id="search-input"
        type="search"
        value={query}
        onChange={e => setQuery(e.target.value)}
        placeholder="Search articles..."
        aria-label="Search articles"
      />
      <button type="submit" disabled={isLoading}>
        {isLoading ? "Searching..." : "Search"}
      </button>
    </form>
  );
}

// Good: small, focused, reusable custom hook.
function useDebounce(value, delay) {
  const [debounced, setDebounced] = useState(value);
  useEffect(() => {
    const timer = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(timer);
  }, [value, delay]);
  return debounced;
}
            

SearchBar uses semantic form elements, accessible labels (sr-only, aria-label), clear naming (handleSubmit, isLoading), and a disabled state. useDebounce is a small, focused, reusable hook.

Try it

  • Code Minifier

    Minify your production code for optimal delivery.

  • Code Diff

    Review code changes during refactoring for best practice adherence.

Common mistakes

The mistake

Using <div onClick> instead of <button> for interactive elements

The fix

Use semantic <button> for clickable actions. It is keyboard accessible (Enter/Space), focusable, and announced correctly by screen readers. <div onClick> requires manual accessibility work that is easy to get wrong.

The mistake

Creating large components with many responsibilities

The fix

Keep components small and focused on one thing. Extract reusable logic into custom hooks, split large UI into smaller sub-components, and aim for components under 150-200 lines. Small components are easier to test, reuse, and reason about.

Practice React Best Practices

3 exercises

Practice React Best Practices

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors