---
title: "CSS Styling"
description: "Hono provides a robust, experimental CSS-in-JS solution designed to work seamlessly in both server-side rendering (SSR) and client-side DOM environments. This subsystem addresses the challenge of m..."
last_updated: "2026-07-02T09:13:47.180045+00:00"
canonical_url: "https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/rendering-jsx/css-styling"
---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [src/middleware/secure-headers/secure-headers.ts](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts)
- [package.json](https://github.com/blade47/hono/blob/main/package.json)
- [src/helper/css/common.ts](https://github.com/blade47/hono/blob/main/src/helper/css/common.ts)
- [src/jsx/dom/render.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts)
- [src/helper/css/index.ts](https://github.com/blade47/hono/blob/main/src/helper/css/index.ts)
- [src/jsx/streaming.ts](https://github.com/blade47/hono/blob/main/src/jsx/streaming.ts)
- [src/jsx/utils.ts](https://github.com/blade47/hono/blob/main/src/jsx/utils.ts)
- [src/jsx/dom/css.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/css.ts)
- [src/middleware/compress/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/compress/index.ts)
- [src/jsx/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/components.ts)
- [src/jsx/dom/intrinsic-element/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/intrinsic-element/components.ts)
- [src/helper/ssg/ssg.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/ssg.ts)
- [src/jsx/intrinsic-element/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/intrinsic-element/components.ts)
- [src/jsx/base.ts](https://github.com/blade47/hono/blob/main/src/jsx/base.ts)
- [src/utils/html.ts](https://github.com/blade47/hono/blob/main/src/utils/html.ts)
- [jsr.json](https://github.com/blade47/hono/blob/main/jsr.json)
- [src/jsx/jsx-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/jsx-runtime.ts)
- [src/helper/html/index.ts](https://github.com/blade47/hono/blob/main/src/helper/html/index.ts)
- [src/helper/ssg/utils.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/utils.ts)
- [src/helper/dev/index.ts](https://github.com/blade47/hono/blob/main/src/helper/dev/index.ts)
- [src/middleware/jsx-renderer/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/jsx-renderer/index.ts)
- [src/jsx/intrinsic-element/common.ts](https://github.com/blade47/hono/blob/main/src/jsx/intrinsic-element/common.ts)
- [src/helper/ssg/index.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/index.ts)
- [src/adapter/deno/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/deno/index.ts)
- [src/jsx/index.ts](https://github.com/blade47/hono/blob/main/src/jsx/index.ts)
- [src/utils/compress.ts](https://github.com/blade47/hono/blob/main/src/utils/compress.ts)
- [src/jsx/jsx-dev-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/jsx-dev-runtime.ts)
</details>

Hono provides a robust, experimental CSS-in-JS solution designed to work seamlessly in both server-side rendering (SSR) and client-side DOM environments. This subsystem addresses the challenge of managing scoped styles in a modular application by generating hash-based class names at runtime, minimizing style collisions, and supporting efficient style injection.

At its core, the CSS styling mechanism treats CSS rules as structured data. By utilizing template literals, it allows developers to define styles naturally, while the underlying helper functions transform these templates into minified style strings and associated class name objects. These objects encapsulate selectors, class identifiers, and the actual style string, which are then used by the rendering engine to either inject standard `<style>` tags during SSR or dynamically update the document’s stylesheet via `CSSStyleSheet` in the DOM.

The system is highly integrated with Hono’s JSX ecosystem. When used in a server environment, the styling helper manages style injection through callback mechanisms that hook into the HTML string rendering flow. In the browser, the DOM-specific CSS module provides an efficient bridge to the browser’s native CSS Object Model (CSSOM). This dual-mode approach ensures that whether the site is served via static generation or dynamic requests, styles are handled in a performant, scoped-by-default, and standard-compliant manner.

## Style String Minification

The subsystem includes a robust minification engine that operates directly on the raw CSS template string. It uses a series of regular expressions to strip unnecessary whitespace, comments, and redundant semicolons, effectively reducing the payload size before the styles are rendered into the final output.

The `minify` function utilizes a complex regex `minifyCssRe` that matches string literals as a protected group to ensure that content inside quotes is not unintentionally modified during the stripping process.

```typescript
// Example of the minification mechanism logic
export const minify = (css: string): string => {
  return css.replace(minifyCssRe, (_, $1, $2, $3, $4) => $1 || $2 || $3 || $4 || '')
}
```
Sources: [src/helper/css/common.ts:100-102](https://github.com/blade47/hono/blob/main/src/helper/css/common.ts#L100-L102)

## Context-Aware Style Management

The `createCssContext` function is the factory that configures the styling environment. It manages state between renders via a `WeakMap`, allowing the engine to track which class names have already been injected into the current request context.

During SSR, if a style has not been rendered yet, a callback is registered. When the stream is finalized, this callback resolves the missing styles and injects them into the document, ensuring that only necessary styles are shipped.

```mermaid
flowchart TD
    A[Render Request] --> B{Style in Context?}
    B -- Yes --> C[Return cached class name]
    B -- No --> D[Register CSS injection callback]
    D --> E[Inject style via <style> tag or script]
```
Sources: [src/helper/css/index.ts:71-122](https://github.com/blade47/hono/blob/main/src/helper/css/index.ts#L71-L122)

## CSSOM Injection Strategy

In the DOM environment, the CSS styling mechanism bypasses standard string injection in favor of direct manipulation of `CSSStyleSheet`. The `createCssJsxDomObjects` function manages a singleton stylesheet entry for the application.

1. `findStyleSheet` attempts to locate the `<style>` tag by ID.
2. If found, it attaches a `Set` to the object to track `addedStyles` locally, preventing duplicate rule insertions.
3. The `insertRule` function uses `sheet.insertRule` to push new definitions to the browser engine, which is significantly faster than DOM tree manipulation for high-frequency style updates.

> [!NOTE]
> The styling subsystem uses a specific internal identifier, `DEFAULT_STYLE_ID` ('hono-css'), to locate or create the `<style>` tag used for injection.

Sources: [src/jsx/dom/css.ts:77-113](https://github.com/blade47/hono/blob/main/src/jsx/dom/css.ts#L77-L113)

## Usage Example

The following example demonstrates how to define scoped styles using the CSS helper and apply them to JSX components.

```typescript
import { css, cx } from 'hono/css'

const buttonClass = css`
  /* Custom label */
  background-color: blue;
  color: white;
  padding: 10px;
`

export const App = () => (
  <button className={cx(buttonClass, 'my-other-class')}>
    Click Me
  </button>
)
```
Sources: [src/helper/css/index.ts:224-231](https://github.com/blade47/hono/blob/main/src/helper/css/index.ts#L224-L231)

## Design Trade-offs

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| **Hash-based naming** | Guaranteed uniqueness, avoids style leaks | Slightly longer CSS file/style tags |
| **Runtime Minification** | Clean output even with messy templates | Slight CPU overhead during first render |
| **WeakMap for Context** | Efficient garbage collection of contexts | Requires object references for context storage |

Sources: [src/helper/css/common.ts:43-50](https://github.com/blade47/hono/blob/main/src/helper/css/common.ts#L43-L50), [src/helper/css/index.ts:82-83](https://github.com/blade47/hono/blob/main/src/helper/css/index.ts#L82-L83)

## Related

- [JSX Renderer](https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/rendering-jsx/jsx-renderer)


## Sitemap

See the full [sitemap](https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/llms.txt) for all pages in this wiki.