Update x-for directive documentation on table elements

[NightFurySL2001]

No description provided.

[calebporzio]

PR Review: #4730 — Update x-for directive documentation on table elements

Type: Docs
Verdict: Request changes

What's happening (plain English)

This PR makes two kinds of changes to the x-for docs page:

1. Minor fixes (good): Formats the "two rules" as a numbered list, fixes a missing space before "elements", and consolidates a paragraph break. These are all fine.

2. New section (~150 lines): Adds a "Limitations in <table>" section explaining that HTML's <template> element doesn't work as expected inside <table> due to the browser's HTML parser stripping non-table elements from table context. It provides 4 workarounds with full code examples.

Problems

1. Code errors in the examples:

• Workaround [Feature] Add .editorconfig file #2 (line 217 in the file) has broken HTML: <tr x-text="color"></td> — closing tag is </td> instead of </tr>, and x-text on a <tr> doesn't make sense. This would confuse anyone trying to copy-paste it.
• The <tbody> example's structure is malformed overall — tags don't match.

2. Security concern in workaround #4:

<tr x-html="colors.map((color, idx) => `<td>${color}</td><td>${idx}</td>`).join('')">

This uses x-html with template literals. While the example itself uses hardcoded data, it teaches a pattern that leads directly to XSS if users substitute user-provided data. Alpine docs should not encourage x-html patterns without security warnings, and ideally should avoid them in beginner-facing content.

3. Disproportionate length:
This new section (~150 lines) is longer than the rest of the x-for documentation combined. Four separate workarounds with full code examples is excessive for what is fundamentally a browser HTML parser behavior, not an Alpine bug.

4. Framing:
The section says this is "currently impossible" — framing a browser HTML spec limitation as an Alpine limitation. This is just how <template> works in table context per the HTML spec.

5. Style inconsistency:
Examples use x-data="the_data" with a separate <script> tag, while the rest of the docs page uses inline x-data="{ ... }".

Other approaches considered

1. Just add a one-paragraph note — A brief mention that <template> inside <table> has browser parsing limitations, with a link to the discussion thread. This is the Alpine-style approach: minimal, practical, "go read more if you need to." Much better fit.
2. Link to an external guide or discussion — The GitHub discussion (Help need about strange issue of x-for. #935) already covers this well. The docs could simply reference it.
3. What this PR does (4 full workarounds) — Too much content for a niche edge case. Makes the page feel like a troubleshooting guide rather than a directive reference.

Changes Made

No changes made. The issues require contributor input or a fundamental restructuring of the section.

Test Results

Docs-only PR — no tests applicable. CI passes (build: ✅).

Code Review

• packages/docs/src/en/directives/for.md: The minor fixes (numbered list, space fix, paragraph consolidation) are all good. The new <table> section has code errors, a security-concerning pattern, and is too long.

Security

The x-html workaround (workaround #4) encourages unsafe patterns. While the example data is hardcoded, the pattern x-html="array.map(item => \${item}`)"` will be copied by users with dynamic/user data, creating XSS vulnerabilities.

Verdict

Request changes. The minor formatting fixes are welcome, but the large new section needs work:

1. Fix the broken HTML in workaround [Feature] Add .editorconfig file #2
2. Either remove the x-html workaround (Add .prevent modifier to click-handler #4) or add a prominent security warning
3. Strongly recommend: Trim to a single paragraph + one workaround (workaround Struggling with x-class binding #1 is the simplest and most correct). Link to the GitHub discussion for anyone who needs more options
4. Reframe as a browser limitation, not an Alpine one

The core information is useful — people do hit this — but the current form is too verbose and contains errors. A concise version would be a good addition to the docs.

---

Reviewed by Claude

[calebporzio]

Thanks for raising this issue, @NightFurySL2001! Your PR identified a real pain point that users have been hitting since 2020.

I've opened two PRs to address this:

1. Warn when x-for template has multiple root elements #4752 — Quick fix: adds a console.warn when multiple root elements are silently dropped, and documents the <tr>-as-root workaround for tables
2. Support multiple root elements in x-for templates #4750 — Full fix: x-for now supports multiple root elements per iteration, so this just works:

<tr>
    <template x-for="(color, idx) in colors">
        <td x-text="color"></td>
        <td x-text="idx"></td>
    </template>
</tr>

You're credited as a co-author on both commits. Closing this in favor of the above PRs.

[NightFurySL2001]

That looks great, thanks! Sorry was busy with Lunar New Year so hadn't have chance to update, but glad to see the x-for is getting more support!