Using the safe attribute

    Estimated reading time: 4 minutes

    Every child expression in Kita Html renders without escaping by default. To escape user input, apply the safe attribute to the nearest native element wrapping the expression.

    Native elements

    Add safe to the element that directly contains the dynamic content. The runtime passes all children through HTML entity escaping before concatenation.

    const 
    const html: JSX.Element
    html     = <
    JSX.IntrinsicElements.div: JSX.HtmlTag
    div     
    JSX.HtmlTag.safe?: boolean | undefined
    When 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-attribute
    safe    >{
    let userInput: "<script>alert('XSS')</script>"
    userInput    }</
    JSX.IntrinsicElements.div: JSX.HtmlTag
    div    >    

    <div>&lt;script>alert(&#39;XSS&#39;)&lt;/script></div>

    safe={true} is equivalent to safe. kita-html check only trusts these two forms; safe={false} and dynamic values such as safe={escape} are checked as if the attribute were missing, because the check cannot prove they are true at runtime.

    Without safe, malicious input executes. Consider a user profile where the description field contains </div><script>fetch('/steal', {method: 'POST', body: document.cookie})</script>. Rendering this without escaping closes the container early, injects a script tag, and runs arbitrary code. The safe attribute converts < to &lt; (along with &, ", and '), so the payload renders as text.

    Place safe on the innermost element that holds the untrusted value. Do not add it to a parent wrapper, as that would escape the HTML of child components too.

    function 
    function UserCard({ name, bio }: {
    name: string;
    bio: string;
}): JSX.Element
    UserCard    ({ 
    name: string
    name    , 
    bio: string
    bio     }: { 
    name: string
    name    : string; 
    bio: string
    bio    : string }) {    
  return (
    <
    JSX.IntrinsicElements.div: JSX.HtmlTag
    div     
    JSX.HtmlTag.class?: string | (string | number | boolean | null | undefined)[] | undefined
    The html class property. You can use an array to represent conditional class
names. Similar to the clsx package behavior.
    @example
    <div class={['a', true && 'b', false && 'c', 'd']} />
'<div class="a b d"></div>'

<div class={['class-a class-b', true && 'class-c']} />
'<div class="class-a class-b class-c"></div>'
    class    ="card">    
      <
    JSX.IntrinsicElements.h2: JSX.HtmlTag
    h2     
    JSX.HtmlTag.safe?: boolean | undefined
    When 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-attribute
    safe    >{
    name: string
    name    }</
    JSX.IntrinsicElements.h2: JSX.HtmlTag
    h2    >    
      <
    JSX.IntrinsicElements.p: JSX.HtmlTag
    p     
    JSX.HtmlTag.safe?: boolean | undefined
    When 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-attribute
    safe    >{
    bio: string
    bio    }</
    JSX.IntrinsicElements.p: JSX.HtmlTag
    p    >    
    </
    JSX.IntrinsicElements.div: JSX.HtmlTag
    div    >    
  )
}

    <div class="card">
  <h2>Name</h2>
  <p>Bio</p>
</div>

    Component children

    The safe attribute only applies to native elements and Fragment. If you pass an unsafe value as a child to a component, you must either escape it manually or wrap it in a Fragment with the safe attribute, which escapes it. This prevents components from accidentally rendering unescaped HTML when they receive dynamic content as children.

    let html: JSX.Element
    html     = (    
  <
    function MyComponent({ children }: {
    children: Children;
}): JSX.Element
    MyComponent    >    
    <
    function Fragment(props: PropsWithChildren<Pick<JSX.HtmlTag, "safe">>): JSX.Element
    A JSX Fragment is used to return multiple elements from a component.
    @example
    // renders <div>1</div> and <div>2</div> without needing a wrapper element
const html = <><div>1</div><div>2</div></>

// Html.Fragment is the same as <>...</>
const html = <Html.Fragment><div>1</div><div>2</div></Html.Fragment>
    Fragment     
    safe?: boolean | undefined
    When 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-attribute
    safe    >{
    let userInput: string
    userInput    }</
    function Fragment(props: PropsWithChildren<Pick<JSX.HtmlTag, "safe">>): JSX.Element
    A JSX Fragment is used to return multiple elements from a component.
    @example
    // renders <div>1</div> and <div>2</div> without needing a wrapper element
const html = <><div>1</div><div>2</div></>

// Html.Fragment is the same as <>...</>
const html = <Html.Fragment><div>1</div><div>2</div></Html.Fragment>
    Fragment    >    
  </
    function MyComponent({ children }: {
    children: Children;
}): JSX.Element
    MyComponent    >    
)

// Or escape explicitly

    let html: JSX.Element
    html     = <
    function MyComponent({ children }: {
    children: Children;
}): JSX.Element
    MyComponent    >{
    function escapeHtml(this: void, value: any): string
    Escapes a string for safe use as HTML text content. If the value is not a string, it is
coerced to one with its own toString() method.
    

    If the
{@linkcode
Bun
}
runtime is available, this function will be swapped out to
    

    {@linkcode
Bun.escapeHTML
}
.
    @paramvalue  The value to escape.@returnsThe  escaped string.
    escapeHtml    (
    let userInput: string
    userInput    )}</
    function MyComponent({ children }: {
    children: Children;
}): JSX.Element
    MyComponent    >
    <div>User input!</div>

    Safety rules

    The XSS tooling classifies JSX child expressions by TypeScript type. These types are safe without escaping:

    Type or expressionWhy it is safe
    number, boolean, bigint, null, undefinedCannot contain HTML markup.
    String literals, such as 'hello'Known at compile time.
    JSX.Element and ChildrenAlready rendered by Kita Html.
    escapeHtml(), escape(), and e templatesEscaped explicitly.
    Variables starting with safeTreated as a deliberate suppression.

    These types need safe, explicit escaping, or a justified suppression:

    Type or expressionWhy it is unsafe
    stringDynamic text may contain HTML.
    anyThe tooling cannot verify the actual value type.
    Objects rendered through toString()The output may contain HTML.

    Union types are safe only when every member is safe. For example, number | boolean is safe, but string | number is unsafe because one branch may contain dynamic text. Content inside <script> elements is exempt from analysis because script content is intended to be executable and is not subject to HTML escaping rules.

    const 
    const condition: true
    condition     = true    
const 
    const safeValue: 42
    safeValue     = 42    
const 
    const unsafeString: "user input"
    unsafeString     = 'user input'    

;<
    JSX.IntrinsicElements.div: JSX.HtmlTag
    div    >{
    const condition: true
    condition     ? 
    const safeValue: 42
    safeValue     : unsafeString}</
    JSX.IntrinsicElements.div: JSX.HtmlTag
    div    >
    Content may introduce an XSS vulnerability and must be marked with the `safe` attribute.
See https://html.kitajs.org/TS88601

    Template literal helper

    e is a tagged template alias of escape(). It escapes the entire resulting string, including the literal parts, so use it for plain text outside of JSX.

    import { 
    const e: (this: void, strings: TemplateStringsArray, ...values: any[]) => string
    Alias of
{@linkcode
escape
}
to reduce verbosity.
    @example
    import { e } from '@kitajs/html'

<div>{e`My name is ${user.name}!`}</div>;
    e     } from '@kitajs/html'    

const 
    const html: string
    html     = 
    const e: (this: void, strings: TemplateStringsArray, ...values: any[]) => string
    Alias of
{@linkcode
escape
}
to reduce verbosity.
    @example
    import { e } from '@kitajs/html'

<div>{e`My name is ${user.name}!`}</div>;
    e    `Hello, ${
    const userName: "<script>untrusted()</script>"
    userName    }!`
    Hello, &lt;script>untrusted()&lt;/script>!

    Suppression conventions

    When kita-html check flags a value that you know is safe, you can suppress the warning without adding safe to the element, which would escape all children and potentially break components.

    Danger

    Suppressing warnings is dangerous because it allows unescaped HTML to slip through. Only use these techniques when you have a guarantee of safety.

    Prefix the variable name with safe. The check treats identifiers named safe, or starting with safe followed by a non-lowercase character (such as safeContent or safe_html), as pre-escaped. Names like safety are still checked.

    const 
    const safeContent: string
    safeContent     = 
    function sanitizeElsewhere(raw: string): string
    sanitizeElsewhere    (
    const rawInput: "<script>alert('XSS')</script>"
    rawInput    )    
const 
    const html: JSX.Element
    html     = <
    JSX.IntrinsicElements.div: JSX.HtmlTag
    div    >{
    const safeContent: string
    safeContent    }</
    JSX.IntrinsicElements.div: JSX.HtmlTag
    div    >    

    <div>&lt;script&gt;alert('XSS')&lt;/script&gt;</div>

    Following the same logic, prefixing a variable with unsafe explicitly marks it as unescaped and triggers error TS88601 if used in JSX.

    const 
    const unsafeContent: "My safe string"
    unsafeContent     = 'My safe string' as 
    type const = "My safe string"
    const    
const 
    const html: JSX.Element
    html     = <
    JSX.IntrinsicElements.div: JSX.HtmlTag
    div    >{unsafeContent}</
    JSX.IntrinsicElements.div: JSX.HtmlTag
    div    >
    Content may introduce an XSS vulnerability and must be marked with the `safe` attribute.
See https://html.kitajs.org/TS88601
    <div>My safe string</div>
    Warning

    Manual casts and naming conventions are not enforced by the compiler. They rely on developer discipline and code reviews to ensure safety. Use them judiciously and document the rationale for any exceptions.

    Cast the expression to 'safe' inline. kita-html check then skips that specific usage and does not warn about possible XSS vulnerabilities.

    const 
    const html: JSX.Element
    html     = <
    JSX.IntrinsicElements.div: JSX.HtmlTag
    div    >{
    const content: string
    content     as 'safe'}</
    JSX.IntrinsicElements.div: JSX.HtmlTag
    div    >
    <div>
  <script>
    untrusted();
  </script>
</div>