Elements & attributes

How JSX elements and attributes map to HTML.

Lowercase elements are HTML#

A lowercase tag is an HTML element; an uppercase one is a component. Void elements (img, br, input, …) render without a closing tag.

import { renderToString } from "@vincle/core";

const html = await renderToString(
  <>
    <input type="text" />
    <br />
  </>,
);

<input type="text" /><br />

A void element takes no children#

HTML has no form for content inside a void element: a parser would move it. So any children other than undefined throws, even a value that renders nothing ({list.length > 0 && <b>x</b>} throws on an empty list too), and the mistake shows in development, not only when real data arrives.

[vincle/core] <img> is a void element and cannot have children: move the content next to it, not inside.

<img src={src}>Caption</img>       // ❌ throws
<img src={src} alt="Caption" />    // ✅
<figure><img src={src} /><figcaption>Caption</figcaption></figure>  // ✅

The error is thrown when the element is created, so JSX built outside a component throws before renderToString is called. To catch it while writing, enable void-dom-elements-no-children (eslint-plugin-react, ported by oxlint). It flags explicit children only: children passed through a spread still reach the runtime check.

Attributes#

Most names pass through unchanged. The React spellings map to their HTML names:

When both spellings reach one element, the HTML name wins and the React one is dropped: no merge, no warning. Prefer the HTML names: they match the output.

import { renderToString } from "@vincle/core";

const html = await renderToString(<div className="foo" class="bar" />);

<div class="bar"></div>

Boolean and falsy values#

null and undefined omit the attribute. On an HTML boolean attribute (disabled, hidden, checked…), false omits it and true renders the bare name; on any other attribute, true and false render as text.

<button disabled={isBusy}>Save</button>
// isBusy true  → <button disabled>Save</button>
// isBusy false → <button>Save</button>

The style attribute#

style accepts either a string or a CSSProperties object. Object values use camelCase keys (like React) and are converted to kebab-case CSS properties.

import { renderToString } from "@vincle/core";

// String style
const html1 = await renderToString(<p style="color: red; font-size: 1.5rem;">Hello</p>);

// Object style (camelCase → kebab-case conversion)
const html2 = await renderToString(<p style={{ color: "red", fontFamily: "sans-serif" }}>Hello</p>);

A string is your declaration list, escaped for the attribute and otherwise emitted as written. An object is data: names carrying CSS syntax are dropped and values are CSS-escaped, so a value cannot add a declaration. See the security model.

Event handlers#

A function has no HTML form, and there is no client runtime to attach it to: any function-valued attribute throws at render time, on* or not. A string handler (onClick="doThing()") is escaped, but the JavaScript inside is yours: never interpolate user data there. The no-unsafe-event-handlers rule flags the practice at the source.

Custom attributes#

Any name renders as written (data-*, aria-*, hx-get), as long as it is valid: no whitespace, quote, <, >, /, = or control character.

Where to next#

• First render: your first component
• Security model: the URL allowlist