Skip to main content

Common JSX Patterns and Pitfalls #22

📖 Introduction​

After covering the strict rules of closing all tags, we've reached the final article in our series on JSX. Now that you understand the core rules, we can explore some common patterns and pitfalls that you'll encounter in day-to-day development.

This article focuses on practical tips, including the correct way to write comments within your JSX and how to avoid some common mistakes that often trip up developers new to React.

📚 Prerequisites​

Before we begin, please ensure you have a solid grasp of the following concepts:

  • JSX Syntax: You should be comfortable writing JSX, including embedding JavaScript expressions with {}.
  • JavaScript Comments: You should know the difference between single-line (//) and multi-line (/* */) comments in JavaScript.

🎯 Article Outline: What You'll Master​

In this article, you will learn:

  • ✅ How to Write Comments in JSX: The correct syntax for adding comments inside your component's return statement.
  • ✅ Different Commenting Styles: Exploring single-line and multi-line comments within JSX.
  • ✅ Commenting Outside of JSX: Using standard JavaScript comments for logic outside the return statement.
  • ✅ Common Pitfalls: Identifying and avoiding frequent mistakes, such as using HTML-style comments.

🧠 Section 1: The Core Concept: Comments in JSX​

Comments are crucial for making code understandable, but you can't use standard HTML comments (<!-- ... -->) in JSX. If you do, they will be treated as actual DOM nodes and will appear on your page as text.

The reason, as always, goes back to the fact that JSX is JavaScript. To add a comment within the JSX returned by your component, you must use JavaScript's syntax, wrapped in curly braces to signify an expression.

The official syntax is to use curly braces to open a "JavaScript window" and then use a multi-line JavaScript comment inside.

The Correct Syntax:

{/* This is a valid JSX comment. */}

💻 Section 2: Practical Commenting Examples​

Let's see how this works in a real component.

2.1 - Single-Line and Multi-Line Comments​

You can use the {/* ... */} syntax for both single-line and multi-line comments.

// code-block-1.jsx
import React from 'react';

function CommentExample() {
  return (
    <div>
      {/* This is a single-line comment explaining the purpose of the h1. */}
      <h1>My Awesome Component</h1>

      {/*
        This is a multi-line comment.
        It can span several lines and is useful for
        more detailed explanations.
      */}
      <p>Some content goes here.</p>
    </div>
  );
}

2.2 - Comments Outside the return Statement​

It's important to remember that any code outside of the return statement is just standard JavaScript. Here, you can and should use regular JavaScript comments (// for single-line and /* */ for multi-line).

// code-block-2.jsx
import React from 'react';

function DataProcessor() {
  // This is a standard single-line JavaScript comment.
  // We are preparing some data before rendering.
  const data = { value: 42 };

  /*
   * This is a standard multi-line JavaScript comment.
   * The logic below formats the data for display.
   */
  const formattedData = `The value is: ${data.value}`;

  return (
    <div>
      {/* This is a JSX comment inside the return statement. */}
      <p>{formattedData}</p>
    </div>
  );
}

🛠️ Section 3: Common Pitfalls and How to Avoid Them​

Here are some of the most common mistakes developers make when trying to comment in JSX.

3.1 - Pitfall: Using HTML Comments​

Using <!-- ... --> will not work as expected. React will not recognize it as a comment and will try to render it as text.

Incorrect:

// This will render "<!-- My Comment -->" on the page!
<div>
  <!-- My Comment -->
  <p>Some content.</p>
</div>

3.2 - Pitfall: Using JavaScript Single-Line Comments Directly​

You cannot use a // comment directly inside JSX without the curly braces and block comment syntax. This will result in a syntax error because the compiler will try to parse the // as text.

Incorrect:

// This will cause a syntax error!
<div>
  // This is not a valid comment
  <p>Some content.</p>
</div>

A clever workaround: While the official syntax is {/* ... */}, some developers use a variation for single-line comments if they prefer the // style. It's a bit of a hack, but it works because it's still a valid JavaScript expression (that evaluates to nothing).

// This works, but is less common
<div>
  {
    // This is a single-line comment inside a block
  }
  <p>Some content.</p>
</div>

✨ Section 4: Best Practices​

Best Practices:

  • Be Clear and Concise: Write comments to explain the why, not the what. Good code should be self-documenting, so comments should clarify complex logic, business rules, or the reasoning behind a particular implementation.
  • Use {/* ... */} for JSX: Stick to the standard {/* ... */} syntax for comments inside your return statement. It's the most idiomatic and universally understood way.
  • Use // for Logic: Use standard // and /* */ comments for the JavaScript logic outside of your return block.
  • Remove Stale Comments: When you change code, make sure to update or remove any comments that are no longer relevant. An incorrect comment is worse than no comment at all.

💡 Conclusion & Key Takeaways​

This concludes our deep dive into the fundamentals of JSX! You now understand not only the syntax but also the "why" behind its most important rules and patterns.

Let's summarize the key takeaways from this article:

  • JSX Comments are JavaScript Comments: To comment within JSX, you must use JavaScript's multi-line comment syntax /* ... */ wrapped in curly braces {}.
  • HTML Comments Don't Work: <!-- ... --> will be rendered as text, not treated as a comment.
  • Context Matters: Use standard JavaScript comments (// or /* */) for any logic outside of the JSX return block.
  • Clarity is King: Use comments to explain complex parts of your code, not to state the obvious.

Challenge Yourself: Go back to the UserProfile card component you built in a previous lesson. Add a JSX comment above the <img> tag explaining where the image URL comes from. Then, add a standard JavaScript comment in the logic section of the component explaining the structure of the user object.

➡️ Next Steps​

Congratulations on completing the entire "Writing Markup with JSX" series! You have a solid foundation for one of the most critical parts of React.

In the next series, "Adding Styles to Your Application", we will explore the various ways to make your components look great, from plain CSS and inline styles to more advanced techniques like CSS Modules and CSS-in-JS.

Thank you for your dedication. Stay curious, and happy coding!

glossary​

  • JSX Comment: A comment written inside JSX markup using the {/* comment */} syntax.
  • Pitfall: A common mistake or error that is easy to make but can be avoided with knowledge and practice.

Further Reading​