> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/honojs/hono/llms.txt
> Use this file to discover all available pages before exploring further.

# CSS Helper

> Experimental CSS-in-JS helper for Hono with scoped styles

<Warning>
  The CSS Helper is experimental. The API may change in future versions.
</Warning>

The CSS Helper provides CSS-in-JS functionality with automatic scoping, allowing you to write CSS directly in your TypeScript/JavaScript code.

## Import

```typescript theme={null}
import { css, cx, keyframes, Style, createCssContext } from 'hono/css'
```

## Functions

### css()

Defines scoped CSS styles and returns a unique class name.

```typescript theme={null}
function css(
  strings: TemplateStringsArray,
  ...values: CssVariableType[]
): Promise<string>
```

<ParamField path="strings" type="TemplateStringsArray" required>
  The CSS template string
</ParamField>

<ParamField path="values" type="CssVariableType[]" required>
  Values to interpolate into the CSS (variables, other css() results, etc.)
</ParamField>

<ResponseField name="return" type="Promise<string>">
  A unique class name for the scoped styles
</ResponseField>

**Example**

```typescript theme={null}
import { Hono } from 'hono'
import { css, Style } from 'hono/css'
import { html } from 'hono/html'

const app = new Hono()

app.get('/', (c) => {
  const className = css`
    background-color: #f0f0f0;
    color: #333;
    padding: 20px;
    border-radius: 8px;
    
    &:hover {
      background-color: #e0e0e0;
    }
  `
  
  return c.html(html`
    <html>
      <head>
        ${Style()}
      </head>
      <body>
        <div class="${className}">
          Hello, styled world!
        </div>
      </body>
    </html>
  `)
})
```

### cx()

Combines multiple class names, similar to the popular `classnames` library.

```typescript theme={null}
function cx(
  ...args: (CssClassName | Promise<string> | string | boolean | null | undefined)[]
): Promise<string>
```

<ParamField path="args" type="(CssClassName | Promise<string> | string | boolean | null | undefined)[]" required>
  Class names to combine. Falsy values are ignored.
</ParamField>

<ResponseField name="return" type="Promise<string>">
  Combined class names as a single string
</ResponseField>

**Example**

```typescript theme={null}
app.get('/button', (c) => {
  const baseStyles = css`
    padding: 10px 20px;
    border: none;
    border-radius: 4px;
    cursor: pointer;
  `
  
  const primaryStyles = css`
    background-color: #007bff;
    color: white;
  `
  
  const isActive = true
  const activeStyles = css`
    box-shadow: 0 0 0 3px rgba(0, 123, 255, 0.5);
  `
  
  const className = cx(
    baseStyles,
    primaryStyles,
    isActive && activeStyles
  )
  
  return c.html(html`
    <html>
      <head>${Style()}</head>
      <body>
        <button class="${className}">Click me</button>
      </body>
    </html>
  `)
})
```

### keyframes()

Defines CSS keyframe animations.

```typescript theme={null}
function keyframes(
  strings: TemplateStringsArray,
  ...values: CssVariableType[]
): CssClassNameCommon
```

<ParamField path="strings" type="TemplateStringsArray" required>
  The keyframes template string
</ParamField>

<ParamField path="values" type="CssVariableType[]" required>
  Values to interpolate
</ParamField>

<ResponseField name="return" type="CssClassNameCommon">
  A keyframes name that can be used in CSS animations
</ResponseField>

**Example**

```typescript theme={null}
import { css, keyframes, Style } from 'hono/css'
import { html } from 'hono/html'

app.get('/animation', (c) => {
  const fadeIn = keyframes`
    from {
      opacity: 0;
      transform: translateY(-10px);
    }
    to {
      opacity: 1;
      transform: translateY(0);
    }
  `
  
  const animatedBox = css`
    animation: ${fadeIn} 0.5s ease-in-out;
    padding: 20px;
    background: #007bff;
    color: white;
  `
  
  return c.html(html`
    <html>
      <head>${Style()}</head>
      <body>
        <div class="${animatedBox}">Animated content!</div>
      </body>
    </html>
  `)
})
```

### Style()

Renders the `<style>` tag containing all accumulated CSS.

```typescript theme={null}
function Style(args?: { children?: Promise<string>; nonce?: string }): HtmlEscapedString
```

<ParamField path="args.children" type="Promise<string>">
  Optional CSS content to include in the style tag
</ParamField>

<ParamField path="args.nonce" type="string">
  Optional nonce attribute for Content Security Policy
</ParamField>

<ResponseField name="return" type="HtmlEscapedString">
  A style tag containing all CSS styles used in the current render
</ResponseField>

**Example**

```typescript theme={null}
app.get('/', (c) => {
  return c.html(html`
    <html>
      <head>
        <title>My App</title>
        ${Style({ nonce: 'random-nonce-123' })}
      </head>
      <body>
        <!-- Your content -->
      </body>
    </html>
  `)
})
```

### viewTransition()

Creates styles for view transitions API.

```typescript theme={null}
function viewTransition(
  strings: TemplateStringsArray,
  ...values: CssVariableType[]
): Promise<string>

function viewTransition(content: Promise<string>): Promise<string>
function viewTransition(): Promise<string>
```

<ParamField path="strings" type="TemplateStringsArray">
  The CSS template for view transition
</ParamField>

<ParamField path="values" type="CssVariableType[]">
  Values to interpolate
</ParamField>

<ResponseField name="return" type="Promise<string>">
  A view transition name
</ResponseField>

**Example**

```typescript theme={null}
import { css, viewTransition, Style } from 'hono/css'
import { html } from 'hono/html'

app.get('/transition', (c) => {
  const transition = viewTransition`
    slide-from-right
  `
  
  const element = css`
    view-transition-name: ${transition};
    padding: 20px;
  `
  
  return c.html(html`
    <html>
      <head>${Style()}</head>
      <body>
        <div class="${element}">Transitioning element</div>
      </body>
    </html>
  `)
})
```

### createCssContext()

Creates an isolated CSS context with a custom style ID.

```typescript theme={null}
function createCssContext({ id }: { id: string }): {
  css: CssType
  cx: CxType
  keyframes: KeyframesType
  viewTransition: ViewTransitionType
  Style: StyleType
}
```

<ParamField path="id" type="string" required>
  A unique identifier for the style tag
</ParamField>

<ResponseField name="return" type="object">
  An object containing isolated versions of `css`, `cx`, `keyframes`, `viewTransition`, and `Style`
</ResponseField>

**Example**

```typescript theme={null}
import { createCssContext } from 'hono/css'

// Create isolated context for a specific part of your app
const { css, Style } = createCssContext({ id: 'my-component' })

app.get('/component', (c) => {
  const className = css`
    color: red;
  `
  
  return c.html(html`
    <html>
      <head>${Style()}</head>
      <body>
        <div class="${className}">Isolated styles</div>
      </body>
    </html>
  `)
})
```

## Features

### Automatic Scoping

All styles defined with `css()` are automatically scoped with unique class names, preventing style conflicts:

```typescript theme={null}
const style1 = css`color: red;`
const style2 = css`color: blue;`
// Generates unique class names like: css-abc123, css-def456
```

### Nesting Support

Supports CSS nesting for pseudo-classes and nested selectors:

```typescript theme={null}
const button = css`
  padding: 10px;
  
  &:hover {
    background: #eee;
  }
  
  &.active {
    font-weight: bold;
  }
`
```

### CSS Variables

Interpolate values and other styles:

```typescript theme={null}
const primaryColor = '#007bff'
const spacing = '20px'

const card = css`
  padding: ${spacing};
  background: ${primaryColor};
  border-radius: 8px;
`
```

## Performance Considerations

* Styles are generated on-demand during rendering
* Duplicate styles are automatically deduplicated
* The Style component must be included in the `<head>` for styles to render

## Types

```typescript theme={null}
type CssClassName = HtmlEscapedString & CssClassNameCommon

interface CssClassNameCommon {
  [CLASS_NAME]: string
  [STYLE_STRING]: string
  [SELECTOR]: string
  [SELECTORS]: Array<{
    [CLASS_NAME]: string
    [STYLE_STRING]: string
  }>
}

type CssVariableType = string | number | CssClassNameCommon
```
