Async components

Estimated reading time: 2 minutes

A Kita Html component can be an async function. When it is, the JSX expression evaluates to a Promise<string> instead of a string.

async function function UserCard({ id }: {
    id: string;
}): Promise<string>
UserCard({ id: stringid }: { id: stringid: string }) {
  const const user: {
    name: string;
}
user = await let db: {
    getUser(id: string): Promise<{
        name: string;
    }>;
}
db.function getUser(id: string): Promise<{
    name: string;
}>
getUser(id: stringid)
  return <JSX.IntrinsicElements.div: JSX.HtmlTagdiv JSX.HtmlTag.safe?: boolean | undefinedWhen set to true, all inner content (html or not) of this tag will be escaped
when evaluated.
Warning: This will escape even inner jsx tags. You should only use this in the
most inner tag of the html tree.
@example<div>{'<script />'}</div>
'<div><script /></div>'
<div safe>{'<script />'}</div>
'<div><script /></div>'
<div><div>{'<script />'}</div></div>
'<div><div><script /></div></div>'

// Escapes even inner jsx tags
<div safe><div>{'<script />'}</div></div>
'<div><div><script /></div></div>'
@defaultfalse@seehttps ://html.kitajs.org/guide/xss/safe-attributesafe>User card for user: {const user: {
    name: string;
}
user.name: stringname}</JSX.IntrinsicElements.div: JSX.HtmlTagdiv>
}

const const html: JSX.Elementhtml = <function UserCard({ id }: {
    id: string;
}): Promise<string>
UserCard id: stringid="123" />
// html is Promise<string>

<div>User card for user: John Doe</div>

Promise propagation

When any child in a component tree is async, the entire parent chain becomes async automatically. The runtime detects promises during child concatenation and wraps the result in Promise.all. No manual promise handling is required at intermediate levels.

function function Page(): JSX.ElementPage() {
  return (
    <JSX.IntrinsicElements.div: JSX.HtmlTagdiv>
      <function UserCard({ id }: {
    id: string;
}): Promise<string>
UserCard id: stringid="123" />
      <JSX.IntrinsicElements.p: JSX.HtmlTagp>Static content</JSX.IntrinsicElements.p: JSX.HtmlTagp>
    </JSX.IntrinsicElements.div: JSX.HtmlTagdiv>
  )
}

const const html: stringhtml = await (<function Page(): JSX.ElementPage />)
// Page() returns Promise<string> because UserCard is async

<div>
  <div>User card for id: 123</div>
  <p>Static content</p>
</div>

This propagation is transitive. If UserCard is nested three levels deep, every ancestor up to the root becomes a Promise<string>.

JSX.Element type

The type JSX.Element is defined as string | Promise<string>. Any component tree may contain async components, so the type covers both cases. When you are certain that a tree is fully synchronous, you can cast the result to string.

// When you know the tree is sync-only
const const html: stringhtml = (<function StaticPage(): JSX.ElementStaticPage />) as string

<div>Static page content</div>

See design decisions for why TypeScript cannot narrow this type.

Awaiting the result

If you need the resolved HTML string, await the result. If you are passing it to a stream or to a framework integration that handles promises, you can pass the promise directly without awaiting.

// Await when you need the string
const html = await (<Page />)
response.end(html)

// Pass directly when the consumer handles promises, such as the Fastify or Express plugins
reply.html(<Page />)

#Async components

#Promise propagation

#JSX.Element type

#Awaiting the result

Async components

Promise propagation

JSX.Element type

Awaiting the result