Skip to content

Styling

Style Xote apps with plain CSS, and let classes, inline styles and data attributes follow your signals.

docs/guides/styling.md
Raw Markdown

Xote has no styling system of its own: you write CSS and point elements at it with class, style and data attributes. What Xote adds is that any of those can follow a signal, so the page restyles itself when state changes.

Add a stylesheet

The simplest setup is a plain CSS file linked from index.html. Vite processes it in development and bundles it for production:

1<link rel="stylesheet" href="/src/styles.css" />

You can also import CSS from a ReScript module. ReScript has no CSS import syntax, so use a raw top-level import; Vite picks it up like any other import:

1// App.res
2%%raw(`import "./App.css"`)

This keeps a component's styles next to its code, which is handy once the app grows.

Use static classes

class takes a string, exactly like HTML's class attribute:

1@xote.component
2let make = () => <section class="card card-elevated"> {"Static classes"} </section>

Switch classes with state

Read a signal in the class expression. Under @xote.component, that attribute becomes its own reactive binding, so only the attribute updates when the signal changes:

1let isOpen = Signal.make(false)
2
3@xote.component
4let make = () =>
5 <div class={Signal.get(isOpen) ? "panel panel-open" : "panel"}>
6 <button onClick={_ => Signal.update(isOpen, v => !v)}> {"Toggle"} </button>
7 </div>

When several classes toggle independently, a small helper keeps the markup readable. Signal reads inside its arguments are still tracked, because they appear in the attribute:

1let classNames = (pairs: array<(string, bool)>) =>
2 pairs->Array.filterMap(((name, on)) => on ? Some(name) : None)->Array.join(" ")
3
4@xote.component
5let make = () =>
6 <li
7 class={classNames([
8 ("option", true),
9 ("option-selected", Signal.get(selected)),
10 ("option-disabled", Signal.get(disabled)),
11 ])}>
12 {"Item"}
13 </li>

Set inline styles

style takes a CSS declaration string, like the HTML attribute (not an object). Inline styles are best for values that really are dynamic, such as a width or a position:

1let progress = Signal.make(40)
2
3@xote.component
4let make = () =>
5 <div class="bar">
6 <div class="bar-fill" style={`width: ${Int.toString(Signal.get(progress))}%`} />
7 </div>

For everything else, prefer a class: it keeps the look in your CSS, where hover states and media queries live.

Style with data attributes

Data attributes are a good fit for state that CSS should react to, like a status or a variant. Set them through the attrs prop. A value there can be a plain string, a signal, or a () => … function:

1let status = Signal.make("idle")
2
3@xote.component
4let make = () =>
5 <span class="badge" attrs=[("data-status", () => Signal.get(status))]>
6 {Signal.get(status)}
7 </span>
1.badge[data-status="saving"] { opacity: 0.6; }
2.badge[data-status="error"] { color: crimson; }

attrs is not rewritten by @xote.component. Pass the signal itself or a function, as above; a bare Signal.get(status) there is read once and never updates.

Theme with a signal

Keep the theme in a signal and expose it to CSS as a data attribute. For a section of the page, put it on that element:

1let theme = Signal.make("dark")
2
3@xote.component
4let make = () =>
5 <div class="app" attrs=[("data-theme", theme)]>
6 <button onClick={_ => Signal.update(theme, t => t == "dark" ? "light" : "dark")}>
7 {"Switch theme"}
8 </button>
9 </div>

To theme the whole document, including <body>, set the attribute on <html> from an effect. The effect re-runs whenever the theme changes. It touches document, so if your app also renders on the server, only start it in the browser:

1@val @scope("document") external documentElement: Dom.element = "documentElement"
2@send external setAttribute: (Dom.element, string, string) => unit = "setAttribute"
3
4if SSRContext.isClient {
5 Effect.run(() => {
6 documentElement->setAttribute("data-theme", Signal.get(theme))
7 None
8 })
9}

Then define your colours as CSS custom properties per theme:

1:root { --bg: #0b0d0c; --text: #f2f4ee; }
2[data-theme="light"] { --bg: #ffffff; --text: #0b0d0c; }
3body { background: var(--bg); color: var(--text); }

Switching the theme now changes one attribute, and the browser restyles everything that uses the variables.

Common mistakes

  • Passing an object to style. style is a string of declarations, as in HTML: "width: 40%; color: red".
  • Expecting attrs to track Signal.get. attrs entries are read once unless the value is a signal or a function.
  • Rebuilding markup to change a look. Swapping whole elements to change colours is slower and loses focus. Toggle a class or data attribute instead.
  • Hiding a read in a let. let cls = Signal.get(isOpen) ? "a" : "b" in the component body is read once. Put the expression in the attribute, where the annotation can track it. See Thinking in signals.

Summary

Xote has no styling system: elements get CSS through class, style (a CSS declaration string) and attributes (attrs, or the data object). Each of these can be static or reactive. Reactive styling is attribute-level: when a signal changes, only that attribute is rewritten; elements are not rebuilt. The one rule that matters most: reactive values in class/style come from a signal read in the attribute expression (PPX) or a signal/thunk value, while attrs and data entries are never rewritten by the PPX and MUST be given a signal or a thunk to stay live.

Availability

ItemImport / entryFirst stableChanged in 7.2.0Needs the PPX
class, style, id, title, hidden propsxote (JSX)7.0.0—No
Inline Signal.get in class/stylexote7.1.0—Yes (@xote.component)
attrs escape hatch; removing an attribute with Nonexote7.1.0—No
data object prop (left as written by the PPX)xote7.1.0—No
View.onMount (DOM work after mount)xote7.2.0 (new)—No
SSRContext.isClient / onClientxote, xote/ssr-contextstable (all 7.x)—No

Rules

  1. class takes one space-separated string. Accepted shapes: string, Signal.t<string>, unit => string, MaybeSignal.t<string>. className is not a prop (compile error).
  2. Under @xote.component, a class or style expression on an intrinsic element that reads a signal becomes a reactive leaf: only that attribute updates when the signal changes.
  3. style takes a CSS declaration string ("width: 40%; color: red"), with the same accepted shapes as class. The prop's type is generic, so a ReScript object or record compiles but renders style="[object Object]".
  4. attrs is array<(string, 'a)>: every entry has the same value type. Values may be string, Signal.t<string>, unit => string, MaybeSignal.t<string>, option<string> (None removes the attribute), or a View.attrValue built with View.attr/View.signalAttr/View.computedAttr. To mix static and reactive entries in one array, build every entry with View.attr/View.signalAttr/View.computedAttr.
  5. The PPX leaves attrs, data and event handlers exactly as written. attrs=[("data-state", Signal.get(state))] is read once and never updates; use ("data-state", state) or ("data-state", () => Signal.get(state)).
  6. An attrs entry is applied after the typed props; for the same attribute name the attrs entry wins, and the last entry for a key wins.
  7. A thunk or signal whose value is None (or null/undefined) removes the attribute; returning Some("") sets it present and empty. Use this for presence-based selectors such as [data-open].
  8. The data prop is typed Obj.t: an object whose keys become data-<key> attributes, each value static, a signal, or a thunk. Building it requires Obj.magic; prefer attrs with explicit data-* names.
  9. Boolean attributes (hidden, disabled, …) are present when true and removed when false.
  10. CSS files are bundler inputs. Link them from index.html, or import them from a ReScript module with %%raw(import "./File.css"); the path is resolved relative to the compiled .res.mjs (next to the .res when "in-source": true).
  11. Code that touches document or window (for example setting data-theme on <html>) MUST NOT run during server rendering or prerendering. Guard it with SSRContext.isClient/SSRContext.onClient, or run it in View.onMount.
  12. Restyling SHOULD toggle classes or data attributes, not swap elements: swapping rebuilds DOM and loses focus, selection and transitions.

API

NameSignatureBehaviour
class propstring | Signal.t<string> | unit => string | MaybeSignal.t<string>Sets class.
style propsame as class (string content)Sets the style attribute.
hidden propbool | Signal.t<bool> | unit => boolPresence attribute.
attrs proparray<(string, 'a)>Any attribute; one value type per array.
data propObj.tObject of data-* values.
View.attr(string, string) => (string, attrValue)Static entry for attrs.
View.signalAttr(string, Signal.t<string>) => (string, attrValue)Signal entry.
View.computedAttr(string, unit => string) => (string, attrValue)Derived entry.
SSRContext.isClientbooltrue when document existed when Xote loaded.
SSRContext.onClient(unit => 'a) => option<'a>Runs only in the browser.

Patterns

Toggle a class — Use when: a component has visual states.

1let isOpen = Signal.make(false)
2
3@xote.component
4let make = () =>
5 <div class={Signal.get(isOpen) ? "panel panel-open" : "panel"}>
6 <button onClick={_ => Signal.update(isOpen, v => !v)}> {"Toggle"} </button>
7 </div>

Several independent classes — Use when: more than one flag affects the class list. The helper call sits in the attribute, so its signal reads are tracked.

1let classNames = (pairs: array<(string, bool)>) =>
2 pairs->Array.filterMap(((name, on)) => on ? Some(name) : None)->Array.join(" ")
3
4@xote.component
5let make = () =>
6 <li
7 class={classNames([
8 ("option", true),
9 ("option-selected", Signal.get(selected)),
10 ("option-disabled", Signal.get(disabled)),
11 ])}>
12 {"Item"}
13 </li>

Dynamic inline style — Use when: a value is continuous (width, position, progress).

1let progress = Signal.make(40)
2
3@xote.component
4let make = () =>
5 <div class="bar">
6 <div class="bar-fill" style={`width: ${Int.toString(Signal.get(progress))}%`} />
7 </div>

Data attributes for CSS state — Use when: CSS should branch on an enumerated state.

1let status = Signal.make("idle")
2
3@xote.component
4let make = () =>
5 <span class="badge" attrs=[("data-status", status)]> {Signal.get(status)} </span>
1.badge[data-status="saving"] { opacity: 0.6; }
2.badge[data-status="error"] { color: crimson; }

Presence attribute — Use when: a selector tests for presence ([data-open]).

1@xote.component
2let make = () =>
3 <div attrs=[("data-open", () => Signal.get(isOpen) ? Some("") : None)] />

Mixed static and reactive attributes — Use when: one attrs array needs both.

1@xote.component
2let make = () =>
3 <div attrs=[View.attr("role", "status"), View.signalAttr("data-theme", theme)] />

App-wide theme — Use when: the theme applies to <html>/<body>. Guard for the server.

1let theme = Signal.make("dark")
2
3@val @scope("document") external documentElement: Dom.element = "documentElement"
4@send external setAttribute: (Dom.element, string, string) => unit = "setAttribute"
5
6if SSRContext.isClient {
7 Effect.run(() => {
8 documentElement->setAttribute("data-theme", Signal.get(theme))
9 None
10 })
11}
1:root { --bg: #0b0d0c; --text: #f2f4ee; }
2[data-theme="light"] { --bg: #ffffff; --text: #0b0d0c; }
3body { background: var(--bg); color: var(--text); }

Component-scoped stylesheet — Use when: styles live next to a component.

1// Card.res
2%%raw(`import "./Card.css"`)
3
4@xote.component
5let make = (~children: View.node) => <section class="card"> {children} </section>

Anti-patterns

  1. Reading a signal in attrs directly. Wrong: attrs=[("data-status", Signal.get(status))]. Symptom: the attribute keeps its first value forever. Right: attrs=[("data-status", status)] or ("data-status", () => Signal.get(status)). Why: the PPX does not rewrite attrs; the expression is evaluated once.

  2. Object style. Wrong: style={{"color": "red"}}. Symptom: compiles; the DOM gets style="[object Object]"; no styling applies. Right: style="color: red" or a template string.

  3. Mixing value types in attrs. Wrong: attrs=[("data-a", "x"), ("data-theme", theme)]. Symptom: compile error This has type: Signal.t<string> But it's expected to have type: string. Right: attrs=[View.attr("data-a", "x"), View.signalAttr("data-theme", theme)].

  4. Computing the class in the component body. Wrong: let cls = Signal.get(isOpen) ? "a" : "b" then <div class=cls />. Symptom: the class never changes. Right: put the expression in the attribute. Why: the component body runs once, untracked.

  5. Touching document at module level. Wrong: an unguarded module-level Effect.run that calls documentElement->setAttribute(…). Symptom: prerendering or server rendering crashes with "document is not defined". Right: guard with if SSRContext.isClient { … }, or do it in View.onMount.

Edge cases

  • class given an array compiles (the prop is generic) and renders the array joined with commas. Always join to a space-separated string.
  • SSRContext.isClient is evaluated once, when Xote's modules load (typeof document !== 'undefined'). In a test runner that installs jsdom after importing modules, it is false; see the Testing guide.
  • A signal passed directly (class={theme}) and a thunk (class={() => …}) both create a reactive leaf without the PPX.
  • SVG presentation attributes (fill, stroke, strokeWidth, opacity, transform, …) are typed props with the same accepted shapes as class.
  • Prefer CSS custom properties for theme values; a single attribute change restyles every consumer without touching many elements.

SSR and hydration

  • class, style, attrs and data render into the HTML with their values at render time; hydration attaches the reactive leaves to the existing elements, so later signal changes update those attributes in place.
  • A theme stored only in the browser (e.g. localStorage) cannot be known on the server: the first paint uses the server default. Set the data-theme attribute with an inline script in the HTML <head> before the stylesheet loads to avoid a flash.
  • %%raw CSS imports are handled by Vite in both client and SSR builds.

Verify

  • Mount in jsdom and read element.className, element.getAttribute("style"), element.getAttribute("data-…") after Signal.set; Zekr has Dom.Assert.toHaveClass and Dom.Assert.toHaveAttribute.
  • SSR.renderToString(() => <Comp />) shows the initial attributes as HTML.
  • Compile error "The field className does not belong to type XoteJSX.Elements.props": use class.
  • /docs/learn/rendering — attribute rules in general.
  • /docs/guides/forms — value/checked/disabled properties.
  • /docs/learn/lifecycle — View.onMount for DOM work.
  • /docs/guides/deploying — keeping browser-only code out of the server.
  • /docs/api/view — View.attr, View.signalAttr, View.computedAttr.