---
title: Server-Side Rendering
description: Guidelines and patterns for SSR and hydration safety in Moraine and SolidStart.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Server-Side Rendering

> Guidelines and patterns for SSR and hydration safety in Moraine and SolidStart.

Moraine supports SolidJS server rendering and hydration. Your application must still render the
same initial state on the server and client, defer browser-only work, and create conditional JSX
only when its branch renders.

This guide covers IDs, portals, content ownership, responsive state, and locale.

## Deterministic Hydration IDs

Accessible components need matching IDs between elements, for example a trigger's `aria-controls` and a content panel's `id`. Random IDs differ between server and client and cause hydration mismatches.

Use `createId` from `moraine/utils` to generate IDs that match across server rendering and client hydration. It builds on Solid's `createUniqueId`. Pass an accessor as the first argument to prefer a caller-provided ID, and a prefix as the second:

```tsx
import { createId } from 'moraine/utils'

function CustomField() {
  const id = createId() // Returns an accessor with the same ID on the server and the client

  return (
    <div>
      <label for={id()}>Username</label>
      <input id={id()} type="text" />
    </div>
  )
}
```

## Hydration-Safe Portals

Overlays such as `Dialog`, `Sheet`, `Drawer`, `Popover`, `Tooltip`, `DropdownMenu`, and `ContextMenu` render their content through a Solid `<Portal>`. The portal mounts into the `body` of the trigger's document, or into the `mount` element when you set one.

In Moraine:

- Overlays default to closed, so the server output contains only the trigger.
- Portals emit no server markup, so overlay content renders only on the client, even when an overlay starts open. The server and initial client trees match.
- Read browser APIs in `onMount` or event handlers. For browser-only content, keep the server and
  initial client tree identical, then reveal that content after mounting.

```tsx
import { Button, Dialog } from 'moraine'

export function UserDialog() {
  return (
    <Dialog>
      <Dialog.Trigger as={Button}>Edit Profile</Dialog.Trigger>
      {/* Content portals to the body on the client only, so hydration matches */}
      <Dialog.Content title="Edit Profile">
        <p>Update your profile details below.</p>
      </Dialog.Content>
    </Dialog>
  )
}
```

## Conditional JSX and item content

Create JSX inside the branch that renders it. For collection items with optional panels, use a
`content` getter so an inactive panel does not consume hydration IDs before it mounts:

```tsx
import { Tabs } from 'moraine'

export function SettingsTabs() {
  return (
    <Tabs
      items={[
        {
          value: 'account',
          label: 'Account',
          get content() {
            return <p>Account settings</p>
          },
        },
        {
          value: 'notifications',
          label: 'Notifications',
          get content() {
            return <p>Notification settings</p>
          },
        },
      ]}
    />
  )
}
```

The same rule applies to JSX panel data in [Accordion](https://moraine.subf.dev/components/accordion.md) and
[Stepper](https://moraine.subf.dev/components/stepper.md). Keep server and client item order and initial selection equal.

## Render-function children

Some props accept either JSX or a function `(props) => JSX.Element`, including children of
[Button](https://moraine.subf.dev/components/button.md), [ToggleButton](https://moraine.subf.dev/components/toggle-button.md),
[CopyButton](https://moraine.subf.dev/components/copy-button.md), [Slider](https://moraine.subf.dev/components/slider.md),
[BaseSelect](https://moraine.subf.dev/components/base-select.md) trigger and item, [Dialog](https://moraine.subf.dev/components/dialog.md),
[BaseDialog](https://moraine.subf.dev/components/base-dialog.md), [Sheet](https://moraine.subf.dev/components/sheet.md), and [Drawer](https://moraine.subf.dev/components/drawer.md) content, and
[Resizable](https://moraine.subf.dev/components/resizable.md) handle.

Declare the function parameter even when the callback does not use it. TypeScript still accepts a
zero-argument function for that prop type. Moraine calls a zero-argument function as an accessor
and does not mount it with a component boundary. Use a parameter when the callback depends on a
Solid owner, lifecycle, or owned reactive computation.

[Field](https://moraine.subf.dev/components/field.md) children call every function with the field state, with or without a
declared parameter. The call is tracked, so signals read directly in the function body re-run it.

## Responsive Queries in SSR

Browser APIs such as `window.matchMedia` do not exist on the server. A component that renders different layouts by screen width needs a deterministic server default.

Moraine's `createMediaQuery` takes a `defaultValue` (default `false`) that is the state during SSR and the first client render. It updates from `matchMedia` after mount:

```tsx
import { createMediaQuery } from 'moraine/utils'
import { Show } from 'solid-js'

export function Navigation() {
  // false on the server and during hydration; follows matchMedia after mount
  const isDesktop = createMediaQuery('(min-width: 1024px)', false)

  return (
    <nav>
      <Show when={isDesktop()} fallback={<MobileDrawer />}>
        <DesktopNav />
      </Show>
    </nav>
  )
}
```

## Transition Presence & Exit Lifecycles

Solid's `<Show>` unmounts elements as soon as its condition becomes false. Moraine components use `createTransitionPresence` internally to keep exiting overlays mounted while CSS exit animations run.

During server rendering:

- Hidden or transitioning elements keep deterministic closed states.
- Animation variables such as `--mo-collapsible-content-height` start at safe initial values (`0px`) without DOM measurement.

## Locale and Direction

`MoraineProvider` renders the same locale on the server and during hydration. SSR and the first client render use `en-US`. A root provider then follows `navigator.language` unless you set `locale` or `detectLocale={false}`. To render localized text on the server, pass `locale` from a cookie or an `Accept-Language` header. The provider's `dir` prop changes component behavior but does not set a `dir` attribute; set `dir` on `<html>` for layout. See the [Localization guide](https://moraine.subf.dev/docs/localization.md).

## Best Practices for SSR Safety

1. **Avoid `window` or `document` in the component body**: Read window dimensions, `localStorage`, or DOM properties inside `onMount` or user event handlers (`onClick`, `onInput`), never while the component runs.
2. **Deterministic initial state**: Initialize controlled signals with static defaults that the server evaluates the same way as the client.
3. **Use Moraine primitives for overlays**: Built-in primitives already manage portals, scroll locks, and focus containment, so you do not need custom SSR guards.

