# miso

> miso is a small, fast and composable Haskell library for building web and native user interfaces. Compiles to WebAssembly or JavaScript.

The complete documentation of miso, from https://haskell-miso.org, as Markdown. An index of the individual pages is at https://haskell-miso.org/llms.txt


---

# Introduction

> What miso is, the problems it solves, and where its ideas come from.

Source: https://haskell-miso.org/docs/introduction/

`miso` is a library for building web and native user interface applications. It provides a [React](https://react.dev)-like programming experience for a simple Haskell dialect that emphasises **performance**, **purity**, **simplicity**, **extensibility** and **composability**.

## What miso addresses

miso covers the common areas of web development so that you can spend your time on your application:

- **DOM manipulation** — miso uses a [Virtual DOM](https://en.wikipedia.org/wiki/Virtual_DOM) with a diffing algorithm that is responsible for all DOM modification and `Component` lifecycle hooks.
- **Event delegation** — all event listeners are attached to a top-level element (typically `<body>`). When raised, events are routed through the virtual DOM to Haskell handlers that change application state. Both the `capture` and `bubble` phases are virtualised.
- **Prerendering** — the server delivers HTML before the JavaScript or WebAssembly bootstraps. Instead of an initial draw, the client populates the virtual DOM from the real DOM ("hydration"), which avoids a redraw and helps SEO. `Miso.Html.Render` renders on the server; `miso` hydrates on the client.
- **Components** — a `Component` is a self-contained miso application bundling its state, the logic that updates it and a function that renders it. Components nest to arbitrary depth.
- **Custom renderers** — the underlying DOM operations are abstracted so a different rendering engine can be plugged in. This is how [miso targets mobile devices](https://haskell-miso.org/docs/native/overview/) through Lynx.
- **Lifecycle hooks** — `mount` and `unmount` on components, `onCreated` and `onDestroyed` on elements. Commonly used for component communication and third-party JavaScript integration.
- **State management** — component `model` state is manipulated with `Miso.Lens` or `Miso.State`.
- **HTTP / cookies** — `Miso.Fetch` wraps the Fetch API and `Miso.Cookie` the CookieStore API, each with an asynchronous callback-based `Effect` and a synchronous `_`-suffixed `IO` variant.

## Architecture

- **React** — miso implements a subset of the React architecture internals: components, lifecycle hooks, virtual DOM, event delegation, along with the Fragment, Props and Context API features.
- **Elm** — miso also implements the Elm architecture (model–view–update) and the `mailbox` communication pattern.

## Native (mobile)

Beyond the browser, miso targets native mobile devices by driving the [Lynx](https://lynxjs.org) runtime instead of the DOM. The same MVU model, `Component` API, event delegation and virtual-DOM diffing carry over unchanged — only the element vocabulary differs. The native backend is gated behind the `native` cabal flag; web and WASM builds are unaffected. See the [native section](https://haskell-miso.org/docs/native/overview/) for the dual-thread architecture.

## Where to next

- [Installation](https://haskell-miso.org/docs/installation/) — set up the WASM toolchain and build the sample app.
- [Your first Component](https://haskell-miso.org/docs/your-first-component/) — the counter, line by line.
- [Thinking in miso](https://haskell-miso.org/docs/thinking/overview/) — how to structure a real application.


---

# Installation

> Get a WebAssembly (or JavaScript) toolchain with nix and build the sample application.

Source: https://haskell-miso.org/docs/installation/

miso applications compile to WebAssembly (the primary target) with the GHC WASM backend, or to JavaScript with the GHC JS backend. The quickest way to a working toolchain is the [miso flake](https://github.com/dmjio/miso/blob/master/flake.nix).

## 1. Build and serve the sampler

With [nix](https://nixos.org) installed (flakes enabled), clone the [sampler](https://github.com/haskell-miso/miso-sampler) and run it — the flake provides the whole WASM toolchain (`wasm32-wasi-cabal`, `wasm32-wasi-ghc`, `http-server`, `ghciwatch`):

```shell
$ git clone https://github.com/haskell-miso/miso-sampler
$ cd miso-sampler
$ nix develop .#wasm --command bash -c 'make all && make serve'
```

Then open [http://localhost:8080](http://localhost:8080). `make all` runs `wasm32-wasi-cabal build`, copies `static/` to `public/`, generates the JS FFI glue with `post-link.mjs` and shrinks the `.wasm` with `wasm-opt`. `make watch` starts `ghciwatch` with the WASM browser GHCi for hot reload. A JavaScript-backend shell (`javascript-unknown-ghcjs-ghc`) is available as `.#ghcjs`, and a plain GHC shell as the default.

## 2. Wire up your own project

A miso executable is an ordinary cabal executable. For WASM builds it is linked as a reactor and exports `hs_start`:

```
executable app
  main-is: Main.hs
  build-depends: base, miso
  if arch(wasm32)
    ghc-options:
      -no-hs-main
      -optl-mexec-model=reactor
      "-optl-Wl,--export=hs_start"
    cpp-options: -DWASM
```

and `Main.hs` exports its entry point when compiled for WASM:

```haskell
{-# LANGUAGE CPP #-}
module Main where

import Miso

#ifdef WASM
foreign export javascript "hs_start" main :: IO ()
#endif

main :: IO ()
main = startApp defaultEvents app
```

The `index.js` loader instantiates the module with a WASI shim and calls `hs_start`. Copy it from the [sampler's static/ folder](https://github.com/haskell-miso/miso-sampler/tree/master/static) to begin.

## Cabal flags

| Flag | Purpose |
| --- | --- |
| `ssr` | Enable when rendering `View`s to HTML on a server: `text` HTML-encodes and `hydrateModel` is honoured. |
| `template-haskell` | Expose `Miso.Lens.TH` (`makeLenses`, `makeClassy`). |
| `native` | Enable the Lynx native backend (`Miso.Native`). |
| `production` | Use the minified JavaScript runtime. |


---

# Your first Component

> A counter: model, update, view — and how to run it with startApp or hydrate with miso.

Source: https://haskell-miso.org/docs/your-first-component/

The core type of miso is `Component`. To define one, use the `component` smart constructor. Below is a simple counter.

```haskell
module Main where

import           Miso
import           Miso.Lens
import qualified Miso.Html.Element  as H
import qualified Miso.Html.Event    as HE
import qualified Miso.Html.Property as HP

-- The four Component type parameters:
--   context - the type of the global context
--   props   - the props inherited from the parent
--   Int     - the type of the Component model
--   Action  - the action that updates the model
counter
  :: Component context props Int Action
counter = component m u v
  where
    -- | Initial model value
    m :: Int
    m = 0

    u :: Action
      -> Effect context props Int Action
    u = \case
      Add      -> this += 1
      Subtract -> this -= 1

    v :: Int
      -> View context props Int Action
    v x = vfrag
      [ H.button_
          [ HE.onClick Add, HP.id_ "add" ]
          [ "+" ]
      , text (ms x)
      , H.button_
          [ HE.onClick Subtract, HP.id_ "subtract" ]
          [ "-" ]
      ]

main :: IO ()
main = startApp defaultEvents counter

data Action
  = Add
  | Subtract
  deriving (Eq, Show)
```

**Live example: The counter, running**

```haskell
data CounterAction = Add | Subtract
  deriving (Show, Eq)

counter
  :: Component ctx () Int CounterAction
counter = component m u v
  where
    m = 0

    u = \case
      Add      -> this += 1
      Subtract -> this -= 1

    v n =
      H.div_ [ HP.class_ "row" ]
        [ H.button_ [ HE.onClick Subtract ] [ "−" ]
        , H.strong_ [] [ text (ms n) ]
        , H.button_ [ HE.onClick Add ] [ "+" ]
        ]
```

Four type parameters follow every `Component`: the global `context` (shared by the whole tree), the `props` passed by the parent, the component's own `model` and the `action` type its `update` consumes. A top-level application fixes `context` and `props` to `()`; the `App` synonym spells that out:

```haskell
type App model action
  = Component () () model action

startApp
  :: Eq model
  => Events
  -> App model action
  -> IO ()
```

## Running it

We recommend `startApp` as the starting point — it sets up event listeners, performs the initial draw and assumes `<body>` is empty. The `miso` function (and `prerender`) assume `<body>` has already been populated by the result of `view`: instead of drawing, `miso` hydrates. If the structures do not match it falls back to drawing from scratch.

```haskell
main :: IO ()
main = miso defaultEvents $ \uri -> counter
-- hydrate a prerendered page
```

## Doing something on mount

It is possible to execute an initial action when a `Component` is first mounted with the `mount` hook (and, similarly, `unmount`):

```haskell
data Action = Init | Add | Subtract

main :: IO ()
main = startApp defaultEvents
  counter { mount = Just Init }

update
  :: Action
  -> Effect context props Int Action
update = \case
  Init -> io_ (consoleLog "hello world!")
  ...
```

> **Note:** `startApp` and `miso` always infer `context` as `()`. Use `startAppWithContext` (or `misoWithContext` when hydrating) to seed a non-trivial context — see [Context](https://haskell-miso.org/docs/context/).


---

# Model–View–Update

> The Elm architecture as miso implements it: a left fold over actions.

Source: https://haskell-miso.org/docs/model-view-update/

The `Component` API adheres to the [Elm](https://elm-lang.org) MVU (model–view–update) interface. It is similar to a left fold over `action`s: the `model` is updated by `update` and rendered by `view`.

```
actions:  Add    Add  Subtract
           │      │      │
           ▼      ▼      ▼
update: 0 ───▶ 1 ───▶ 2 ───▶ 1 ───▶ ...
        │      │      │      │
        ▼      ▼      ▼      ▼
view:   ▢      ▢      ▢      ▢
        (virtual DOM, diffed & patched)
```

*Every action folds into the model; every model is rendered exactly once.*

- **model** — any user-defined type. An `Eq` instance is required (we recommend the derived one): miso only redraws when the model actually changed.
- **view** — the templating function that constructs a new virtual DOM (or HTML when rendering on the server). It is pure: `context -> props -> model -> View`.
- **update** — describes how the model evolves in response to actions raised by the application. It takes any `action`, updates the model and optionally schedules `IO`.

## Why it works

Because `view` is a pure function of state, there is exactly one place where state changes (`update`) and one place where the UI is described (`view`). Effects never run inside `update` — they are *scheduled* and their results come back as new actions, so the fold never observes partial state. This is what makes miso applications easy to reason about, easy to test and trivial to prerender.

Continue with [Components](https://haskell-miso.org/docs/components/) to see how many small MVU loops compose into an application, or read [Thinking in miso](https://haskell-miso.org/docs/thinking/overview/) for a guided walkthrough.


---

# The View DSL

> The View type, element nodes, the smart constructors in Miso.Html.Element and element lifecycle hooks.

Source: https://haskell-miso.org/docs/view-dsl/

A `VNode` represents a DOM element — the most common kind of virtual DOM node. It carries a `Namespace`, a tag name, a list of `Attribute` values and a list of child `View`s.

## The View type

The `View` is a rose tree of nodes, mutually recursive with `Component` through `view`:

```haskell
data View context props model action
  = VNode Namespace Tag [Attribute model action] [View context props model action] DirectEvents
  | VText (Maybe Key) MisoString
  | VComp (SomeComponent context)
  | forall childProps. VCompStatic (StaticPtr (SomeStaticComponent childProps context)) childProps
  | VFrag (Maybe Key) [View context props model action]
  | VContext (context -> View context props model action)
  | VProps   (props   -> View context props model action)
  | VModel   (model   -> View context props model action)

data SomeComponent context
  = forall model action props. (Eq context, Eq model, Eq props)
  => SomeComponent (Maybe Key) props (Component context props model action)
```

`VNode` and `VText` map one-to-one onto the physical DOM. `VComp` and `VFrag` are abstract (they live only in the virtual DOM). The existential `SomeComponent` is what allows embedding polymorphic components in a `View`. `VCompStatic` carries a static pointer to its constructor and is used by the [native dual-thread runtime](https://haskell-miso.org/docs/native/static-mounting/).

`VContext`, `VProps` and `VModel` are not nodes at all, but *accessors*. Each wraps a function from the app-global `context`, the enclosing component's `props` or its `model` to a `View`. The function is applied and the wrapper discarded when the enclosing `View` is built or rendered, so none of the three ever reaches the diff. Build them with `vcontext`, `vprops` and `vmodel` — see [Ambient accessors](https://haskell-miso.org/docs/ambient/).

## Element nodes

```haskell
VNode HTML "div" [ HP.id_ "container" ] [ "Hello, world!" ]
```

In practice you rarely construct `VNode` directly. Use the element smart constructors from `Miso.Html.Element`, which fix the namespace and tag for you:

```haskell
H.div_    [ HP.id_ "container" ]        [ "Hello, world!" ]
H.button_ [ HE.onClick DoSomething ]    [ "Click me" ]
H.h1_     [ HP.className "title" ]      [ text (ms pageTitle) ]
```

For elements not covered by `Miso.Html.Element`, use `node` (or its synonym `vnode`) directly:

```haskell
node HTML "details" []
  [ node HTML "summary" [] [ "More info" ] ]
```

SVG and MathML elements use the `SVG` and `MATHML` namespaces and are covered by `Miso.Svg.Element` and `Miso.Mathml.Element`. Unlike `VComp` and `VFrag`, a `VNode` has a one-to-one correspondence with a physical DOM element.

- `node` — raw constructor — namespace, tag, attributes, children
- `vnode` — synonym for `node`
- `Miso.Html.Element` — every HTML element (`div_`, `span_`, `input_` …)
- `Miso.Svg.Element` — SVG graphics, animation and container elements
- `Miso.Mathml.Element` — MathML elements

## Lifecycle hooks

Like components, elements expose lifecycle hooks:

- `onBeforeCreated`
- `onCreated` / `onCreatedWith`
- `onBeforeDestroyed` / `onBeforeDestroyedWith`
- `onDestroyed`

These are useful for initialising and tearing down third-party libraries, as in this example using [highlight.js](https://highlightjs.org):

```haskell
{-# LANGUAGE QuasiQuotes      #-}
{-# LANGUAGE MultilineStrings #-}

import Miso
import Miso.FFI.QQ (js)

data Action = Highlight DOMRef

update
  :: Action
  -> Effect context props model Action
update = \case
  Highlight domRef ->
    io_ [js| hljs.highlightElement(${domRef}) |]

view
  :: model
  -> View context props model Action
view _ =
  H.code_ [ onCreatedWith Highlight ]
    [ """
      function addOne (x) { return x + 1; }
      """
    ]
```

As a convention, the `*With` variant of a lifecycle hook (e.g. `onCreatedWith`) provides the target `DOMRef` to the callback.

## The smart constructors, at a glance

- `node, vnode` — build a `VNode`
- `text, vtext` — build a `VText` — see [Text nodes](https://haskell-miso.org/docs/text/)
- `component` — build a `VComp`
- `fragment, vfrag, fragment_, vfrag_` — build a `VFrag`
- `(+>)` — key and mount a child `Component`
- `vcontext, vprops, vmodel` — build a `VContext`, `VProps` or `VModel` — see [Ambient accessors](https://haskell-miso.org/docs/ambient/)


---

# Components

> The Component record, composition with (+>), keys and the mount / unmount lifecycle.

Source: https://haskell-miso.org/docs/components/

A `Component` bundles a model, the `update` that evolves it and the `view` that renders it — plus everything around the edges: subscriptions, lifecycle hooks, a mailbox. Components nest, forming a typed UI tree.

> **Note:** Always build components with the `component` smart constructor — `component m u v` — rather than the `Component` record constructor directly. It fills every other field with sane defaults; override the ones you need with record-update syntax, e.g. `(component m u v) { subs = [...] }`.

## The record

The `component` smart constructor fills in sane defaults; you override fields with record update syntax:

```haskell
data Component context props model action = Component
  { model :: model
    -- initial model
  , hydrateModel :: Maybe (IO model)
    -- optional model to hydrate from (SSR)
  , update
      :: action
      -> Effect context props model action
  , view
      :: model
      -> View context props model action
  , useContext :: Bool
    -- re-render when the global context changes
  , subs :: [ Sub action ]
    -- long-running subscriptions
  , styles :: [ CSS ]
    -- dev only: append <style>/<link> to <head>
  , scripts :: [ JS ]
    -- dev only: append <script> to <head>
  , mountPoint :: Maybe MountPoint
    -- defaults to <body>
  , logLevel :: LogLevel
    -- Off | DebugHydrate | DebugEvents | DebugAll
  , mailbox :: Value -> Maybe action
    -- receive mail from other components
  , eventPropagation :: Bool
    -- let events bubble past this component
  , mount :: Maybe action
    -- action dispatched on mount
  , unmount :: Maybe action
    -- action dispatched on unmount
  , onPropsChanged
      :: Maybe (props -> props -> action)
  }
```

## Composition

Components can contain other components. This is accomplished through the mounting combinator `(+>)`, which encodes a typed component hierarchy. All components in a tree share the same global `context` type.

```haskell
(+>)
  :: (Eq context, Eq model)
  => MisoString
  -> Component context () model action
  -> View context props parentModel parentAction
key +> comp = VComp (SomeComponent (Just (toKey key)) () comp)
```

Practically, using this combinator looks like:

```haskell
viewModel
  :: Int
  -> View context props Int Action
viewModel _ =
  H.div_ [ HP.id_ "container" ]
    [ "counter" +> counter ]
```

The `"counter"` string is a unique `Key` that identifies the component at runtime. Keys matter when diffing two components: when intentionally replacing a component it is important to specify a new key, otherwise the old one will not be unmounted.

It is possible to mount a component with `mount_`, which avoids specifying a key, but this should only be used when you are certain the component will never be diffed against another component. When in doubt, use `(+>)` and key your component. To pass [props](https://haskell-miso.org/docs/props/) use `mountWithProps_` (keyed) or `mountWithProps`.

## Lifecycle hooks

Components are mounted during diffing. All components are equipped with `mount` and `unmount` hooks, allowing custom actions to be dispatched in response to lifecycle events:

```haskell
child :: Component ctx () Model Action
child = (component m u v)
  { mount   = Just Connect
  , unmount = Just Disconnect
  }
```

Element nodes have their own hooks (`onCreated`, `onDestroyed`, …) — see [the View DSL](https://haskell-miso.org/docs/view-dsl/).

**Live example: mount, unmount, subs and the mailbox**

```haskell
-- A parent that mounts and unmounts a keyed child, and
-- logs what the child reports through the mailbox.
data ParentModel = ParentModel
  { _mounted :: Bool
  , _entries :: [MisoString]
  } deriving (Show, Eq)

mounted :: Lens ParentModel Bool
mounted = lens _mounted $ \p x -> p { _mounted = x }

entries :: Lens ParentModel [MisoString]
entries = lens _entries $ \p x -> p { _entries = x }

data ParentAction
  = ToggleChild
  | ChildSaid MisoString
  | BadMail MisoString

parent
  :: Eq ctx
  => Component ctx () ParentModel ParentAction
parent = (component (ParentModel True []) update view)
  { mailbox = checkMail ChildSaid BadMail
    -- receive mail from the child
  }
  where
    update = \case
      ToggleChild -> mounted %= not
      ChildSaid s -> entries %= take 6 . (s :)
      BadMail _   -> pure ()

    view m =
      H.div_ []
        [ H.button_ [ HE.onClick ToggleChild ]
            [ text $ if m ^. mounted
                then "Unmount the clock"
                else "Mount the clock"
            ]
        , if m ^. mounted then "clock" +> clock else "no clock"
        , H.ul_ [ HP.class_ "log" ]
            [ H.li_ [] [ text e ] | e <- m ^. entries ]
        ]

-- The child: a clock that ticks from a subscription and
-- reports its lifecycle to the parent.
data ClockAction = Tick | Mounted | Unmounted

clock
  :: Component ctx () Int ClockAction
clock = (component 0 update view)
  { mount = Just Mounted
    -- dispatched when the component appears
  , unmount = Just Unmounted
    -- ...and when it goes away
  , subs = [ everySecond ]
    -- runs for the component's lifetime
  }
  where
    everySecond sink _ =
      forever (threadDelay 1000000 >> sink Tick)

    update = \case
      Tick      -> this += 1
      Mounted   -> mailParent ("clock mounted" :: MisoString)
      Unmounted -> mailParent ("clock unmounted" :: MisoString)

    view secs =
      H.p_ [] [ "⏱ ", text (ms secs), "s since mount" ]
```

Toggle the clock: the child's `mount` and `unmount` actions run, its `subs` start and stop with it, and it reports back through the parent's `mailbox`. Note the `"clock" +> clock` key — that is what makes the diff mount and unmount rather than patch.


---

# Text nodes

> VText nodes — string literals, HTML encoding on the server and keyed text.

Source: https://haskell-miso.org/docs/text/

A `VText` represents a DOM text node. Text nodes participate in keyed reconciliation.

The simplest way to produce a `VText` is via the `IsString` instance on `View`. String literals inside a child list are automatically promoted to text nodes:

```haskell
H.div_ [] [ "Hello, world!" ]
```

For dynamic content, use the `text` smart constructor with a `MisoString`:

```haskell
H.div_ [] [ text (ms userName) ]
```

### HTML encoding

When compiling with the `ssr` flag, `text` automatically HTML-encodes its argument — `<`, `>`, `&`, `"` and `'` become entities. This prevents accidental XSS when rendering user-supplied strings on the server. To embed trusted, pre-rendered content without escaping use `textRaw`; it is a no-op on the client and bypasses encoding on the server.

```haskell
text    "<b>bold</b>"   -- SSR output: &lt;b&gt;bold&lt;/b&gt;
textRaw "<b>bold</b>"   -- server and client: <b>bold</b>
```

### Concatenating and keying

`text_` accepts a list of strings and joins them with a single space. A `VText` may also carry a `Key` (`textKey`, `textKey_`): keyed text nodes take part in the same reconciliation as keyed elements, so a stable key prevents unnecessary text-node replacement when sibling order changes.

```haskell
H.div_ [] [ text_ [ "Hello", "world" ] ]
-- renders: Hello world

renderItem
  :: Item
  -> View context props model Action
renderItem item =
  H.li_ []
    [ textKey (itemId item) (itemLabel item) ]
```

- `text` — single string, HTML-encoded on the server
- `vtext` — synonym for `text`
- `textRaw` — single string, never HTML-encoded
- `text_` — list of strings joined with a space
- `textKey` — single keyed string
- `textKey_` — list of keyed strings joined with a space


---

# Fragments

> VFrag — grouping siblings without a wrapper element, with keyed variants.

Source: https://haskell-miso.org/docs/fragments/

A `VFrag` groups sibling nodes without a wrapper element in the DOM. Fragments participate in keyed reconciliation.

Inspired by [React's Fragment](https://react.dev/reference/react/Fragment) (`<></>`), a `VFrag` is analogous to the browser's `DocumentFragment`:

```haskell
-- Renders two <li> elements as direct
-- siblings, no enclosing element
fragment
  [ H.li_ [] [ "Item A" ]
  , H.li_ [] [ "Item B" ]
  ]

-- Keyed fragment — survives reordering
-- without full teardown / remount
vfrag_ "my-key"
  [ H.li_ [] [ "Item A" ]
  , H.li_ [] [ "Item B" ]
  ]
```

Fragments may be nested. Diffing recurses into nested fragments and processes them as if they were a flat sequence of sibling DOM nodes, so nesting carries no runtime cost beyond the constructor allocation. Empty fragments in child lists are erased before diffing and are therefore a no-op.

- `fragment` — unkeyed fragment
- `vfrag` — unkeyed fragment (alias)
- `fragment_` — keyed fragment
- `vfrag_` — keyed fragment (alias, infix-friendly: ``"key" `vfrag_` [...]``)


---

# Keys

> What keys mean for diffing, identity and preserving DOM references across updates.

Source: https://haskell-miso.org/docs/keys/

A `Key` is a unique identifier used to optimise diffing. Virtual DOM nodes can be keyed with `key_`. Keys have multiple meanings in miso (as in React).

## Keys optimise child-list diffing

When two lists of elements are diffed and all of them have unique keys, diffing large child lists is much faster. This optimisation fires automatically when *all* elements in a child list carry unique keys — unless every node in the list is keyed, it will not.

## Keys compare two identical nodes

If two `VNode`s (or two `VComp`s) are being compared and their keys differ, the old node is destroyed and a new one created. Otherwise the underlying DOM node is kept and its properties diffed. For components, differing keys trigger the `unmount` phase for the old component and the `mount` phase for the new one; the DOM reference is replaced.

## Keys preserve the DOM reference

Because a stable key keeps the same DOM node in place, CSS animations on that node are not interrupted by re-renders. Without a key diffing may recreate the node, resetting any in-progress animation. Assigning a stable key to an animated element guarantees the animation runs to completion.

## Usage

See the `key_` property, and smart constructors like `textKey_`, `vfrag_` and `(+>)`:

```haskell
H.ul_ []
  [ H.li_ [ key_ "key-1" ] [ "a" ]
  , H.li_ [ key_ "key-2" ] [ "b" ]
  , "key-3" +> counter
  , textKey "key-4" "text here"
  , vfrag_ "key-5" [ "foo", "bar" ]
  ]
```


---

# Events

> Event delegation through \<body>, the Events map, defining handlers with on, and decoding events.

Source: https://haskell-miso.org/docs/events/

By default all events are delegated through `<body>`. miso supports both the `capture` and `bubble` phases of browser events, and applications can handle either.

## Using events

miso exposes `defaultEvents` for convenience — commonly used events that are listened for on `<body>` and routed through the `View` to the virtual DOM node that raised them. Other groups are exposed as conveniences too (`keyboardEvents`, `mouseEvents`, `pointerEvents`, `touchEvents`, …). All events required by all your components must be combined when running the application:

```haskell
main =
  startApp
    (defaultEvents <> keyboardEvents <> touchEvents)
    app

touchEvents :: Events
touchEvents = M.fromList
  [ ("touchstart",  BUBBLE)
  , ("touchcancel", BUBBLE)
  , ("touchmove",   BUBBLE)
  , ("touchend",    BUBBLE)
  ]
```

> **Note:** `defaultEvents` contains `blur`, `change`, `click`, `contextmenu`, `dblclick`, `focus`, `input`, `select` and `submit`. Using `onKeyDown` without listening for `keydown` is the classic mistake — enable `DebugEvents` to catch it.

## Defining event handlers

Define your own handlers with the `on` combinator. By default this defines an event in the `BUBBLE` phase; see `onCapture` for the `CAPTURE` phase and `onWithOptions` for `preventDefault` / `stopPropagation`. `Miso.Html.Event` has many predefined events.

```haskell
onChangeWith
  :: (MisoString -> DOMRef -> action)
  -> Attribute model action
onChangeWith = on "change" valueDecoder
```

The `*With` variant of an event (e.g. `onChangeWith`) provides the target `DOMRef` to the callback.

## Decoding events

After an event is raised, information is extracted from it with a `Decoder`. Many common decoders are available in `Miso.Event.Decoder`.

```haskell
data Decoder a = Decoder
  { decoder :: Value -> Parser a
    -- Miso.JSON parser
  , decodeAt :: DecodeTarget
    -- path into the event object
  }

-- | A custom Decoder for the `value`
-- property of an event target.
valueDecoder :: Decoder MisoString
valueDecoder = Decoder {..}
  where
    decodeAt = DecodeTarget ["target"]
    decoder =
      withObject "target" $ \o -> o .: "value"
```

A decoder that reads several fields, used with `on`:

```haskell
clickDecoder :: Decoder (Int, Int)
clickDecoder = Decoder
  { decodeAt = DecodeTarget []
  , decoder = withObject "click" $ \o -> do
      ox <- o .: "offsetX"
      oy <- o .: "offsetY"
      pure (floor ox, floor oy)
  }

view _model =
  H.canvas_
    [ on "click" clickDecoder $ \(x, y) _ _ ->
        Clicked x y
    ]
    []
```

## Try it

**Live example: Built-in handlers and a custom decoder**

```haskell
data EventsModel = EventsModel
  { _typed   :: MisoString
  , _lastKey :: Maybe Int
  , _clickAt :: Maybe (Int, Int)
  } deriving (Show, Eq)

typed :: Lens EventsModel MisoString
typed = lens _typed $ \m x -> m { _typed = x }

lastKey :: Lens EventsModel (Maybe Int)
lastKey = lens _lastKey $ \m x -> m { _lastKey = x }

clickAt :: Lens EventsModel (Maybe (Int, Int))
clickAt = lens _clickAt $ \m x -> m { _clickAt = x }

data EventsAction
  = Typed MisoString
  | Pressed KeyCode
  | ClickedAt (Int, Int)

-- A custom decoder: read offsetX / offsetY from the
-- raw event object.
offsetDecoder :: Decoder (Int, Int)
offsetDecoder = Decoder
  { decodeAt = DecodeTarget []
  , decoder = withObject "click" $ \o -> do
      x <- o .: "offsetX" :: Parser Double
      y <- o .: "offsetY" :: Parser Double
      pure (floor x, floor y)
  }

events
  :: Component ctx () EventsModel EventsAction
events = component (EventsModel "" Nothing Nothing) update view
  where
    update = \case
      Typed s             -> typed .= s
      Pressed (KeyCode k) -> lastKey .= Just k
      ClickedAt xy        -> clickAt .= Just xy

    view m =
      H.div_ []
        [ H.input_
            [ HP.placeholder_ "Type, then press keys…"
            , HE.onInput Typed
              -- "input"   (in defaultEvents)
            , HE.onKeyDown Pressed
              -- "keydown" (needs keyboardEvents)
            ]
        , H.p_ []
            [ "value: ", H.code_ [] [ text (m ^. typed) ] ]
        , H.p_ []
            [ "keyCode: ", text (maybe "–" ms (m ^. lastKey)) ]
        , H.div_
            [ HP.class_ "target"
            , on "click" offsetDecoder $ \xy _ _ ->
                ClickedAt xy
              -- custom decoder
            ]
            [ text $ case m ^. clickAt of
                Nothing ->
                  "click me"
                Just (x, y) ->
                  "clicked at " <> ms x <> "," <> ms y
            ]
        ]
```


---

# Attributes & properties

> The Attribute type, the smart constructors, custom properties and the property-vs-attribute rule.

Source: https://haskell-miso.org/docs/attributes/

The `Attribute` type carries everything that can be attached to a DOM element:

```haskell
data Attribute model action
  = Property MisoString Value
    -- DOM property (key/value)
  | ClassList [MisoString]
    -- CSS class list
  | On (model -> Sink action -> ...)
    -- fully-applied event handler
  | OnStatic
      (StaticPtr (EventHandler model action))
    -- static handler, rebuilt on the
    -- main thread (dual-thread)
  | Styles (Map MisoString MisoString)
    -- inline style map
```

In practice you never construct these directly. Use the smart constructors from `Miso.Html.Property`, `Miso.Html.Event`, `Miso.Property` and `Miso.CSS`:

```haskell
H.div_
  [ HP.id_ "container"
    -- textProp "id"
  , HP.className "card"
    -- ClassList
  , HP.classList_ [ ("active", isActive) ]
    -- ClassList, conditional
  , HP.disabled_
    -- boolProp "disabled" True
  , HE.onClick MyAction
    -- On event handler
  , CSS.style_ [ CSS.display "flex" ]
    -- Styles map
  ]
  []
```

## Custom properties

Use `prop` (or the typed variants `textProp`, `boolProp`, `intProp`, `doubleProp`, `objectProp`) from `Miso.Property` to set arbitrary DOM properties:

```haskell
prop "data-index" (42 :: Int)
-- sets element.data-index = 42

textProp "placeholder" "Search…"
-- sets element.placeholder

boolProp "checked" True
-- sets element.checked = true
```

Note that DOM *properties* and HTML *attributes* are distinct. miso tries to set properties on the DOM node object (e.g. `node.checked`) first, then falls back to setting the HTML attribute (`setAttribute("checked", …)`). This matches what the browser exposes in JavaScript and avoids common pitfalls with boolean attributes.

## Keys

`key_` (and its alias `keyProp`) attaches a reconciliation key to any element. See [Keys](https://haskell-miso.org/docs/keys/) for details.

```haskell
data Item = Item { itemId, itemLabel :: MisoString }

H.li_ [ key_ (itemId item) ] [ text (itemLabel item) ]
```

## Try it

**Live example: Conditional classes, structured styles and properties**

```haskell
data BarModel = BarModel { _pct :: Int }
  deriving (Show, Eq)

pct :: Lens BarModel Int
pct = lens _pct $ \m x -> m { _pct = x }

data BarAction = SetPct MisoString

battery
  :: Component ctx () BarModel BarAction
battery = component (BarModel 65) update view
  where
    update (SetPct v) = pct .= fromMisoString v

    view (BarModel p) =
      H.div_ []
        [ H.div_
            [ HP.class_ "bar-track"
            , HP.title_ (ms p <> "%")
              -- textProp "title"
            ]
            [ H.div_
                [ HP.classList_
                    -- conditional classes
                    [ ("bar", True)
                    , ("bar-low",  p < 30)
                    , ("bar-ok",   p >= 30 && p < 80)
                    , ("bar-full", p >= 80)
                    ]
                , CSS.style_
                    -- structured inline style
                    [ CSS.width (CSS.pct (fromIntegral p))
                    , CSS.transition_ "width"
                        (CSS.ms 250)
                        "ease-out"
                    ]
                ] []
            ]
        , H.input_
            [ HP.type_ "range"
            , HP.min_ "0"
            , HP.max_ "100"
            , HP.value_ (ms p)
            , HE.onInput SetPct
            ]
        , H.p_ [ HP.class_ "muted" ]
            [ H.code_ [] [ text (ms p), "% → ." , text klass ] ]
        ]
      where
        klass | p < 30 = "bar-low"
              | p < 80 = "bar-ok"
              | otherwise = "bar-full"
```


---

# Effects

> The Effect monad: mutating the model, scheduling asynchronous and synchronous IO, and the Sink.

Source: https://haskell-miso.org/docs/effects/

The `Effect` type is used to mutate the `model` over time in response to `action`s. It also allows `IO` to be *scheduled* for evaluation by the miso scheduler. `IO` is never evaluated inside `Effect`, it is only scheduled — there is no `MonadIO` instance.

`Effect` is defined as an `RWS`:

```haskell
type Effect context props model action
  = RWS
      (ComponentInfo context props)
      [Schedule context action]
      model
      ()
```

- The **Reader** portion is `ComponentInfo`: `ask`, `asks` and `Miso.Lens.view` read its fields (the current `ComponentId`, the parent id, the `DOMRef` the component is mounted on, `props`, `context`).
- The **Writer** portion schedules `IO`. `tell` creates a `Schedule` that runs according to its `Synchronicity`; see `withSink`.
- The **State** portion is the `model`: `get`, `put`, `modify` and the `MonadState` lens operators from `Miso.Lens`.

## Asynchronous IO

- `io` — introduce asynchronous IO whose result is dispatched as an action; `io_` discards the result.
- `withSink` — the core function from which most other combinators are defined — gives access to the event `Sink`. The scheduler attaches exception handlers to all IO.
- `issue` — dispatch an action asynchronously (`batch` for several).
- `tell` — for maximum flexibility the `MonadWriter` instance schedules raw `Schedule`s.

```haskell
update
  :: Action
  -> Effect ctx props Model Action
update = \case
  FetchUser uid ->
    io (GotUser <$> lookupUser uid)
    -- async, the result becomes an action
  Log msg ->
    io_ (consoleLog msg)
    -- async, fire and forget
  Tick ->
    withSink $ \sink -> forkTimer (sink Tock)
```

## Synchronous IO

`sync` forces the scheduler to evaluate IO synchronously (`sync_` discards the result). It is recommended to use `io` by default — `sync` *will* block the scheduler. Reserve it for cheap reads such as `localStorage` or measuring a `DOMRef`.

## The Sink

```haskell
type Sink action = action -> IO ()
```

A `Sink` writes any action to the global event queue. Subscriptions receive one; `withSink` hands you the current component's.

## Managing model state

Any `MonadState` function may be used to manipulate the model — `get`, `put`, `modify` — plus the lens operators (`.=`, `%=`, `+=` …) from `Miso.Lens`. See [State & lenses](https://haskell-miso.org/docs/state-and-lenses/).

## Try it

**Live example: io and io_: scheduling asynchronous work**

```haskell
data DiceModel = DiceModel
  { _rolls :: [Int]
  , _busy  :: Bool
  } deriving (Show, Eq)

rolls :: Lens DiceModel [Int]
rolls = lens _rolls $ \m x -> m { _rolls = x }

busy :: Lens DiceModel Bool
busy = lens _busy $ \m x -> m { _busy = x }

data DiceAction = Roll | Rolled Int | Clear

dice
  :: Component ctx () DiceModel DiceAction
dice = component (DiceModel [] False) update view
  where
    update = \case
      -- `io` schedules IO; its result comes
      -- back as another action.
      Roll -> do
        busy .= True
        io $ do
          threadDelay 300000
          -- pretend this is a network call
          r <- mathRandom
          pure (Rolled (1 + floor (r * 6)))
      Rolled n -> do
        rolls %= take 12 . (n :)
        busy .= False
      -- `io_` schedules IO whose result is discarded.
      Clear -> do
        rolls .= []
        io_ (consoleLog "cleared")

    view m =
      H.div_ []
        [ H.button_
            [ HE.onClick Roll
            , boolProp "disabled" (m ^. busy)
            ]
            [ text $ if m ^. busy
                then "rolling…"
                else "Roll a die (async)"
            ]
        , H.button_ [ HE.onClick Clear ] [ "clear" ]
        , H.p_ []
            [ text $ if null (m ^. rolls)
                then "no rolls yet"
                else ms (unwords (map show (m ^. rolls)))
            ]
        ]
```


---

# Context

> The global context: one value shared by the whole component tree, read in view and update, changed with modifyContext.

Source: https://haskell-miso.org/docs/context/

`context` is miso's analogue of [React Context](https://react.dev/learn/passing-data-deeply-with-context): a single, global value shared by *every* component in the tree, without threading it through props at each level. This very site keeps its language table and colour theme there.

Contrast the three pieces of state a component sees, by scope:

- **model** — private to a single component.
- **props** — passed from a parent to its immediate child.
- **context** — global; the same value is visible to the whole tree.

This is why `context` is a type parameter on both `Component` and `View`: it is threaded through the entire tree so that every nested component — reachable via `SomeComponent` — is statically guaranteed to agree on *one* context type. There is exactly one live context value per application.

## Seeding

- `startAppWithContext` — the client entry point, replaces `startApp`.
- `misoWithContext / prerenderWithContext` — the hydrating counterparts of `miso` / `prerender`.
- `toHtmlWith` — supplies the context (with the props and model) when serialising a `View` without starting the runtime — the server-side rendering path. As of 1.14.0 there is no global context cell to seed: `setContext` is gone, the value is passed to the renderer.
- `liveWithContext / reloadWithContext` — context-aware variants of `live` / `reload` for interactive (GHCi) development.

## Reading

As of 1.14.0 a `view` takes only the `model`. The context is read *ambiently* with `vcontext`, so any component — however deeply nested — still reads it synchronously during render, without anything threading it down (see [Ambient accessors](https://haskell-miso.org/docs/ambient/)):

```haskell
view
  :: model
  -> View context props model action
view _model =
  vcontext $ \ctx -> ...
```

Inside `update` it is readable in the `Effect` monad, just like props — use `getContext` (or `Miso.Lens.view` with the `context` lens):

```haskell
update Toggle = do
  ctx <- getContext
  ...
```

## Updating

Mutate the context with `modifyContext` (or `putContext` to replace it):

```haskell
update Toggle =
  modifyContext $ \theme ->
    if theme == Light then Dark else Light
```

## Re-rendering on change

When the context value changes (per its `Eq` instance), every component with `useContext = True` is re-rendered against the new value. `useContext` defaults to `False`, so components opt in:

```haskell
child = (component m u v) { useContext = True }
```

> **Note:** `useContext` controls whether a component *reacts* to context changes, not whether it may *change* the context. A component (typically the top-level one) can call `modifyContext` with `useContext = False`; it simply won't re-render in response. Set `useContext = True` on precisely those components whose `view` depends on the context.

## Try it

**Live example: Reading and changing the site's context**

```haskell
-- This site's context holds the language and the theme.
-- Any component can read it (ambiently, with vcontext) and
-- change it (modifyContext). Only components with
-- useContext = True re-render when it changes.
data ThemeAction = FlipTheme

themeSwitch
  :: Component Ctx () () ThemeAction
themeSwitch = (component () update view)
  { useContext = True }
  where
    update FlipTheme = do
      ctx <- getContext
      -- context is readable in Effect
      let theme =
            if ctxTheme ctx == Dark then Light else Dark
      modifyContext (\c -> c { ctxTheme = theme })
      io_ $ do
        -- persist + apply, like the top bar
        setLocalStorage "miso.theme" (themeCode theme)
        html <- jsg "document" ! "documentElement"
        void $ html # "setAttribute" $
          ("data-theme" :: MisoString, themeCode theme)

    view () =
      -- context is ambient in the view: read it with 'vcontext'
      vcontext $ \ctx ->
        H.div_ []
          [ H.p_ []
              [ "The context says: theme = "
              , H.strong_ []
                  [ text (ms (show (ctxTheme ctx))) ]
              , ", language = "
              , H.strong_ []
                  [ text (langName (ctxLang ctx)) ]
              ]
          , H.button_ [ HE.onClick FlipTheme ]
              [ "Flip the whole site's theme" ]
          , "frozen" +> frozen
          ]

-- A sibling that does not opt in: it keeps showing the
-- context it mounted with.
frozen :: Component Ctx () () ()
frozen = component () (\() -> pure ()) view
  -- useContext defaults to False
  where
    view () =
      vcontext $ \ctx ->
        H.p_ [ HP.class_ "muted" ]
          [ "useContext = False: I still think the theme is "
          , text (ms (show (ctxTheme ctx))) ]
```

The first component opts in with `useContext = True` and re-renders on every change; the second does not, so it keeps showing whatever the context was when it mounted. The button really does change the site's theme — the top bar's toggle and this demo share one value.

## Example: this website

The site's context is a record with the active language, a translation table and the theme. The top bar's dropdown calls `modifyContext`; every page component has `useContext = True` and renders text nodes by looking keys up in the table:

```haskell
data Ctx = Ctx
  { ctxLang    :: Lang
  , ctxCatalog :: Catalog
  , ctxTheme   :: Theme
  } deriving Eq

t :: Ctx -> Key -> View Ctx props model action
t ctx key = text (translate ctx key)

update (SetLang l) = do
  modifyContext (\ctx -> ctx { ctxLang = l })
  io_ (setLocalStorage "miso.lang" (langCode l))
```


---

# Props

> Read-only data passed from a parent to a child at mount time, with mountWithProps\_ and getProps.

Source: https://haskell-miso.org/docs/props/

Inspired by [React props](https://react.dev/learn/passing-props-to-a-component), miso allows a parent component to pass read-only data down to a child via *props*. Props are synchronous: when they change in the parent, the child re-renders.

## Props vs component-local state

- **model** — component-local state, owned and mutated exclusively by the component through its `update`. No other component can write to it directly.
- **props** — data *inherited* from the parent. Props flow downward and are read-only from the child's perspective; the parent decides what to pass at mount time.

This mirrors React's distinction between `useState` and the props a function component receives.

### When to use props

Props suit *metadata* — contextual or configuration data the child needs to know about but should not own: a display name, a theme token, a locale, a read-only identifier. If the data drives the child's own business logic — counters it increments, form fields it edits, async state it manages — it belongs in the child's `model`. Prefer props for "what the child should know" and the model for "what the child should do".

## Props in view and update

As of 1.14.0 `view` takes only the `model`; props are read *ambiently* with `vprops` (see [Ambient accessors](https://haskell-miso.org/docs/ambient/)). Top-level applications have no parent, so their props are `()`:

```haskell
view
  :: model
  -> View context props model action
view _model =
  vprops $ \props -> ...
```

Use `getProps` inside `Effect` (or `Miso.Lens.view props`) to read the current value:

```haskell
update = \case
  SomeAction -> do
    p <- getProps
    io_ (consoleLog (ms (show p)))
```

## Passing props to a child

Use `mountWithProps_` (keyed) or `mountWithProps` (unkeyed) in the parent's `view`:

```haskell
mountWithProps_
  :: (Eq context, Eq model, Eq props)
  => MisoString
  -> props
  -> Component context props model action
  -> View context props parentModel parentAction
```

## Example: child reading parent-supplied props

```haskell
-- The props type: what the parent
-- shares with the child
newtype Greeting = Greeting MisoString
  deriving (Eq)

child
  :: Component () Greeting () ChildAction
child = component () updateChild viewChild
  where
    viewChild
      :: ()
      -> View () Greeting () ChildAction
    viewChild _ =
      vprops $ \(Greeting g) ->
        H.div_ []
          [ text ("Hello, " <> g <> "!") ]

    updateChild
      :: ChildAction
      -> Effect () Greeting () ChildAction
    updateChild = \case
      ReadGreeting -> do
        Greeting g <- getProps
        io_ (consoleLog g)

-- Parent component: owns the greeting,
-- passes it to the child as props
parentComp :: App ParentModel ParentAction
parentComp =
  component (ParentModel "World") noop viewParent
  where
    viewParent
      :: ParentModel
      -> View () () ParentModel ParentAction
    viewParent (ParentModel g) =
      mountWithProps_ "child" (Greeting g) child

newtype ParentModel = ParentModel MisoString
  deriving (Eq)

data ChildAction = ReadGreeting
data ParentAction
```

- Props flow from parent to child explicitly via `mountWithProps_`; the child's context is the shared global context.
- `getProps` inside the child's `update` yields a `Greeting`. The child only sees what the parent chose to share.
- The root `App` always has `context ~ ()` and `props ~ ()`; no plumbing is needed for `startApp`.
- The `onPropsChanged` hook dispatches an action with the previous and current props whenever they change.

## Try it

**Live example: Props flowing from a parent to a child**

```haskell
-- The props type: what the parent shares with the child.
newtype Greeting = Greeting MisoString
  deriving (Show, Eq)

-- The parent owns the name and passes it down as props.
data NamerAction = NameChanged MisoString

namer
  :: Eq ctx
  => Component ctx () MisoString NamerAction
namer = component "World" update view
  where
    update (NameChanged s) = this .= s

    view name =
      H.div_ []
        [ H.input_
            [ HP.value_ name
            , HE.onInput NameChanged
            , HP.placeholder_ "Your name"
            ]
        , mountWithProps_ "greeter" (Greeting name) greeter
          -- keyed, with props
        ]

-- The child reads its props in view and in update.
data GreeterModel = GreeterModel
  { _changes :: Int
  , _shown   :: MisoString
  } deriving (Show, Eq)

changes :: Lens GreeterModel Int
changes = lens _changes $ \m x -> m { _changes = x }

shown :: Lens GreeterModel MisoString
shown = lens _shown $ \m x -> m { _shown = x }

data GreeterAction
  = ShowProps
  | PropsChanged Greeting Greeting

greeter
  :: Component ctx Greeting GreeterModel GreeterAction
greeter = (component (GreeterModel 0 "") update view)
  { onPropsChanged = Just PropsChanged
    -- react when the parent changes props
  }
  where
    update = \case
      PropsChanged _old _new -> changes += 1
      ShowProps -> do
        Greeting g <- getProps
        -- props are readable in Effect
        shown .= "props are: " <> g

    view m =
      -- props are ambient in the view: read them with 'vprops'
      vprops $ \(Greeting g) ->
        H.div_ []
          [ H.p_ [] [ "Hello, ", H.strong_ [] [ text g ], "!" ]
          , H.p_ [ HP.class_ "muted" ]
              [ "props changed ", text (ms (m ^. changes)), " times" ]
          , H.button_ [ HE.onClick ShowProps ]
              [ "show props" ]
          , H.p_ [] [ text (m ^. shown) ]
          ]
```


---

# Ambient accessors

> VContext, VProps and VModel: read the context, props or model anywhere in a view with vcontext, vprops and vmodel.

Source: https://haskell-miso.org/docs/ambient/

As of **1.14.0**, a component's `view` takes only the `model`. The `context` and `props` are read *ambiently* instead — at the point in the tree that actually needs them — with `vcontext` and `vprops`. `vmodel` completes the trio.

These three are *accessors*, not nodes. Each wraps a function from the value to a `View`. The function is applied and the wrapper discarded whenever the enclosing `View` is built or rendered, so `VContext`, `VProps` and `VModel` never appear in the virtual DOM the runtime diffs.

## The trio

- `vcontext` — read the app-global `context`. Synonym: `withContext`.
- `vprops` — read the enclosing component's `props`. Synonym: `withProps`.
- `vmodel` — read the enclosing component's `model`. Synonym: `withModel`.

All three share one shape — a function in, a `View` out:

```haskell
vcontext :: (context -> View context props model action)
         -> View context props model action

vprops   :: (props   -> View context props model action)
         -> View context props model action

vmodel   :: (model   -> View context props model action)
         -> View context props model action
```

## Why they exist

Before 1.14.0, a view was handed all three values as arguments:

```haskell
-- before 1.14.0
view :: context -> props -> model -> View context model action
view ctx props model = ...
```

That meant every helper needing the `context` had to take it as an extra parameter, threaded down through the whole tree — even helpers that used nothing else. Now the view takes only the model, and anything deeper reaches for what it needs, where it needs it:

```haskell
-- 1.14.0
view :: model -> View Ctx props model action
view model =
  H.div_ []
    [ H.h1_ [] [ text (title model) ]
    , themeBadge          -- nothing has to pass it the context
    ]

themeBadge :: View Ctx props model action
themeBadge =
  vcontext $ \ctx ->
    H.span_ [] [ text (themeLabel (ctxTheme ctx)) ]
```

## Scope: what each one sees

Unlike `context`, which is one global value, `props` and `model` are per-component. That is why both are type parameters of `View`: the `props` a `VProps` sees is statically the `props` of the `Component` whose `view` contains it, and a mismatch is a compile-time error.

- **context** — the one live value for the whole tree; every nested component agrees on its type.
- **props** — the enclosing component's own. A child mounted with `mountWithProps` / `vcomp` sees *its* props, never its parent's.
- **model** — likewise the enclosing component's own; a mount boundary forgets the child's model type just as it forgets its props and action.

> **Note:** Accessors add no redraw logic of their own. Whether a component redraws on a `context` change is still decided solely by `useContext`; a component redraws on new `props` from its parent, and on its own `model` changing after an `update`. The accessor is simply re-resolved as part of that redraw.

## vmodel and view

The `model` is the one value the view already receives, so `vmodel` is a convenience rather than a necessity — these two are equivalent:

```haskell
view model = H.p_ [] [ text (ms (count model)) ]

view _ = vmodel $ \model ->
           H.p_ [] [ text (ms (count model)) ]
```

It earns its keep deeper in a tree, where a helper wants the model but sits several combinators away from the `view` that was handed it.

## Why not ImplicitParams or a Reader?

Both are alternatives for ambient values. `ImplicitParams` gives the same "read it where you need it" ergonomics, but is a GHC-specific extension whose constraints leak into every helper's signature. A `Reader` would work on any compiler, but forces a monadic style onto view code that is otherwise plain applicative expressions and lists. The accessors keep the `View` DSL as ordinary Haskell values: just another constructor, resolved by the runtime, with nothing to lift or thread.

## Rendering to HTML

When serialising, a bare `View` under `toHtml` is static markup with `context ~ ()`, `props ~ ()` and `model ~ ()`. A view that reads real values is rendered with `toHtmlWith`, which takes them:

```haskell
toHtmlWith
  :: context
  -> props
  -> model
  -> View context props model action
  -> ByteString

toHtmlWith ctx props model (view comp model)
```

This site's prerenderer does exactly that — there is no global context cell to seed, the value is handed to the renderer. See [HTML & prerendering](https://haskell-miso.org/docs/html-and-prerendering/).

## Try it

The [Context](https://haskell-miso.org/docs/context/) and [Props](https://haskell-miso.org/docs/props/) pages both have live demos whose views read their values through these accessors.


---

# Communication

> Four ways components exchange data: props, context, the asynchronous mailbox and PubSub.

Source: https://haskell-miso.org/docs/communication/

miso provides four mechanisms for components to exchange data.

- **Props** — synchronous, parent-to-child read-only data passed at mount time; see [Props](https://haskell-miso.org/docs/props/).
- **Context** — global data shared by the entire tree; any component can mutate it via `modifyContext` and opt in to re-renders with `useContext`; see [Context](https://haskell-miso.org/docs/context/).
- **Mailbox** — message passing via `mail`, `broadcast`, `checkMail`; any component can send a JSON `Value` to any other by `ComponentId`.
- **PubSub** (`Miso.PubSub`) — publish / subscribe for fan-out messaging across unrelated components.

## The mailbox

Every component has a mailbox — a slot that receives `Value` messages sent by other components. Messages are dispatched asynchronously via the event queue.

### Sending

- `mail componentId msg` — send to a specific `ComponentId` (obtained via `ask` inside `Effect`)
- `mailParent msg` — send to the direct parent
- `mailChildren msg` — send to all immediate children
- `mailAncestors msg` — walk up the hierarchy, delivering to every ancestor
- `mailDescendants msg` — walk down the hierarchy, delivering to every descendant
- `broadcast msg` — deliver to every mounted component except the sender

### Receiving with checkMail

Wire up the `mailbox` field with `checkMail`, which handles JSON parsing and routes to success / error actions:

```haskell
data Action
  = ReceivedMsg MyMsg
  | MailError   MisoString

myComp
  :: Component context props model Action
myComp = (component m u v)
  { mailbox = checkMail ReceivedMsg MailError }
```

### Looking up a ComponentId

```haskell
update = \case
  SendMsg targetId ->
    io_ (mail targetId ("hello" :: MisoString))
  GetMyId -> do
    info <- ask
    let myId = _componentInfoId info
    ...
```

## PubSub

`Miso.PubSub` provides topics: a component `subscribe`s to a topic (receiving messages as actions) and any component may `publish` to it. It is the right tool when the sender does not know who is listening.

```haskell
-- a typed topic; Note has ToJSON / FromJSON
notifications :: Topic Note
notifications = topic "notifications"

update = \case
  Init ->
    subscribe notifications Notified NotifyError
  Notify n ->
    io_ (publish notifications n)
  Notified n -> ...
    -- n :: Note
  NotifyError _ ->
    pure ()
```

## Try it

**Live example: Mailbox and PubSub between siblings**

```haskell
-- Two siblings that do not know each other talk over a
-- PubSub topic; the publisher also mails its parent,
-- which relays the message to every child.
data Note = Note MisoString
  deriving (Show, Eq, Generic, ToJSON, FromJSON)

notes :: Topic Note
notes = topic "demo-notes"

data ChatAction
  = Relayed Note
  | MailErr MisoString

chat
  :: Eq ctx
  => Component ctx () () ChatAction
chat = (component () update view)
  { mailbox = checkMail Relayed MailErr }
  where
    update = \case
      Relayed n -> mailChildren n
        -- parent → all of its children
      MailErr _ -> pure ()

    view _ =
      H.div_ [ HP.class_ "cols" ]
        [ "publisher"  +> publisher
        , "subscriber" +> subscriber
        ]

data PubAction = Send | Draft MisoString

publisher
  :: Component ctx () MisoString PubAction
publisher = component "hello from the publisher" update view
  where
    update = \case
      Draft s -> this .= s
      Send -> do
        s <- get
        io_ (publish notes (Note s))
        -- fan out over the topic (IO)
        mailParent (Note s)
        -- and tell the parent directly

    view s =
      H.div_ []
        [ H.input_ [ HP.value_ s, HE.onInput Draft ]
        , H.button_ [ HE.onClick Send ] [ "publish" ]
        ]

data SubAction
  = Subscribe
  | Got Note
  | Oops MisoString

subscriber
  :: Component ctx () [MisoString] SubAction
subscriber = (component [] update view)
  { mount = Just Subscribe
    -- subscribe on mount
  , mailbox = checkMail Got Oops
    -- also accepts parent mail
  }
  where
    update = \case
      Subscribe    -> subscribe notes Got Oops
      Got (Note s) -> this %= take 5 . (s :)
      Oops _       -> pure ()

    view received =
      H.ul_ [ HP.class_ "log" ]
        [ H.li_ [] [ text s ] | s <- received ]
```

The publisher does two things on send: it `publish`es to a topic the subscriber joined on mount, and it `mailParent`s the parent, which relays with `mailChildren` — so each message arrives at the subscriber twice, once by each route.


---

# Subscriptions

> Long-running sources of actions: subs, startSub / stopSub and createSub.

Source: https://haskell-miso.org/docs/subscriptions/

A `Sub` is any long-running operation that is external to a component but that can write to the component's `Sink`. As of 1.14.0 it is also handed an `IO model`, to read the component's current model on demand. Subs come in two flavours: the static `subs` list and dynamic subs via `startSub` / `stopSub`.

```haskell
type Sub model action =
  Sink action -> IO model -> IO ()
```

## subs

```haskell
main :: IO ()
main = startApp defaultEvents app { subs = [ timerSub ] }

timerSub :: Sub Model Action
timerSub sink _readModel =
  forever $ threadDelay 100000 >> sink Log

data Action = Log
```

The `subs` field contains subs that exist for the lifetime of the component. When it unmounts, they are stopped and their resources finalised. Here is a real one from `Miso.Subscription.OnLine`:

```haskell
onLineSub :: (Bool -> action) -> Sub model action
onLineSub f sink _readModel = createSub acquire release sink
  where
    release (cb1, cb2) = do
      windowRemoveEventListener "online"  cb1
      windowRemoveEventListener "offline" cb2
    acquire = do
      cb1 <- windowAddEventListener "online"
        (const $ sink (f True))
      cb2 <- windowAddEventListener "offline"
        (const $ sink (f False))
      pure (cb1, cb2)
```

## startSub / stopSub

At times it is necessary to dynamically create a sub in response to an event (e.g. starting a `Miso.WebSocket` connection when a user logs in):

```haskell
update = \case
  StartTimer -> startSub ("timer" :: MisoString) timerSub
  StopTimer  -> stopSub "timer"
  Log        -> io_ (consoleLog "log")
  where
    timerSub :: Sub Model Action
    timerSub sink _ =
      forever $ threadDelay 100000 >> sink Log
```

## createSub

`Miso.Subscription.Util.createSub` builds a sub using the `bracket` pattern, ensuring listeners are unregistered when the component unmounts. Use it only when custom event listeners are required; the `Miso.Subscription` modules cover the usual suspects:

- `Miso.Subscription.Mouse` — global pointer position
- `Miso.Subscription.Keyboard` — arrows, WASD, arbitrary key sets
- `Miso.Subscription.Window` — resize, scroll, any window event via `windowSub`
- `Miso.Subscription.History` — `uriSub` / `routerSub` for navigation
- `Miso.Subscription.RAF` — `rAFSub` — `requestAnimationFrame` ticks for 60 FPS animation
- `Miso.Subscription.OnLine` — `navigator.onLine`

## Try it

**Live example: A dynamic subscription with startSub / stopSub**

```haskell
data TimerModel = TimerModel
  { _ticks   :: Int
  , _running :: Bool
  } deriving (Show, Eq)

ticks :: Lens TimerModel Int
ticks = lens _ticks $ \m x -> m { _ticks = x }

running :: Lens TimerModel Bool
running = lens _running $ \m x -> m { _running = x }

data TimerAction = Start | Stop | Ticked

timer
  :: Component ctx () TimerModel TimerAction
timer = component (TimerModel 0 False) update view
  where
    tenTimesASecond :: Sub TimerModel TimerAction
    tenTimesASecond sink _ =
      forever (threadDelay 100000 >> sink Ticked)

    update = \case
      Start -> do
        running .= True
        startSub ("timer" :: MisoString) tenTimesASecond
      Stop -> do
        running .= False
        stopSub ("timer" :: MisoString)
      Ticked ->
        ticks += 1

    view m =
      H.div_ [ HP.class_ "row" ]
        [ H.button_ [ HE.onClick toggle ] [ text label ]
        , H.strong_ []
            [ let (secs, tenths) = (m ^. ticks) `divMod` 10
              in text (ms secs <> "." <> ms tenths <> "s")
            ]
        ]
      where
        toggle = if m ^. running then Stop else Start
        label  = if m ^. running then "Stop" else "Start"
```


---

# State & lenses

> Miso.Lens: the bundled lens library, MonadState operators and three ways to generate lenses.

Source: https://haskell-miso.org/docs/state-and-lenses/

miso bundles a lightweight lens library in `Miso.Lens` to minimise dependencies and payload size. Any lens library (optics, lens) also works — `Miso.Lens` is not required.

## Basic operations

```haskell
view l              -- read a field (MonadReader)
set  l v            -- write a field
over l f            -- modify a field
r ^. l              -- infix read
r & l .~ v          -- infix write
```

## MonadState operators (inside Effect)

```haskell
l .= v    -- set a field
l %= f    -- modify a field
l += n    -- increment a numeric field
l -= n    -- decrement
l *= n    -- multiply
```

## this — the identity lens

When the model *is* the field (e.g. the model is a plain `Int`), use `this`:

```haskell
update = \case
  Increment -> this += 1
  Decrement -> this -= 1
```

## Generating lenses

Three approaches, pick one:

### Template Haskell

```haskell
{-# LANGUAGE TemplateHaskell #-}
import Miso.Lens.TH (makeLenses)

data Model = Model { _count :: Int, _name :: MisoString }
makeLenses ''Model

update = \case
  Increment -> count += 1
  Rename n  -> name .= n
```

### Generics

`Miso.Lens.Generic.field` / `HasLens` derive lenses at compile time using `GHC.Generics` — no splice required. Needs `TypeApplications` and, optionally, `OverloadedLabels` for the `#field` shorthand:

```haskell
{-# LANGUAGE DataKinds, DeriveGeneric #-}
{-# LANGUAGE OverloadedLabels        #-}
{-# LANGUAGE TypeApplications        #-}
import GHC.Generics (Generic)
import Miso.Lens.Generic (field)

data Model = Model
  { count :: Int
  , name  :: MisoString
  } deriving (Eq, Generic)

update = \case
  Increment -> field @"count" += 1
    -- via TypeApplications
  Rename n  -> #name .= n
    -- via OverloadedLabels
```

### Hand-written

```haskell
name :: Lens Person MisoString
name = lens _name $ \p n -> p { _name = n }
```

## Try it

**Live example: Updating a record model through lenses**

```haskell
data Person = Person
  { _name :: MisoString
  , _age  :: Int
  } deriving (Show, Eq)

-- Hand-written lenses (Miso.Lens.TH and
-- Miso.Lens.Generic can write these).
name :: Lens Person MisoString
name = lens _name $ \p n -> p { _name = n }

age :: Lens Person Int
age = lens _age $ \p a -> p { _age = a }

data PersonAction
  = Rename MisoString
  | Birthday
  | Younger

person
  :: Component ctx () Person PersonAction
person = component (Person "Ada" 36) update view
  where
    update = \case
      Rename n -> name .= n
        -- set through a lens
      Birthday -> age += 1
        -- arithmetic through a lens
      Younger  -> age %= max 0 . subtract 1

    view p =
      H.div_ []
        [ H.input_
            [ HP.value_ (p ^. name), HE.onInput Rename ]
        , H.p_ []
            [ text (p ^. name)
            , " is "
            , text (ms (p ^. age))
            , " years old"
            ]
        , H.button_ [ HE.onClick Birthday ] [ "birthday" ]
        , H.button_ [ HE.onClick Younger ] [ "younger" ]
        ]
```


---

# Routing

> Miso.Router: a reversible, type-safe client-side router derived from a sum type.

Source: https://haskell-miso.org/docs/routing/

`Miso.Router` provides a reversible, type-safe client-side router. A `Route` type encodes URL structure; the `Router` class converts between routes and `URI` values in both directions. Use it with `routerSub` or `uriSub` to react to browser navigation. This site's own routing is written with it.

## Defining a Router with Generics

Derive `Router` via `GHC.Generics` — constructor names become path segments (camel-case uses only the first hump; `Index` is the root). Use `Capture`, `Path`, `QueryParam` and `QueryFlag` as fields to describe the URL shape:

```haskell
{-# LANGUAGE DeriveGeneric, DeriveAnyClass #-}
import GHC.Generics
import Miso.Router

data Route
  = Index
    -- "/"
  | About
    -- "/about"
  | Product
      (Capture "id" Int)
      (QueryParam "tab" MisoString)
    -- "/product/42?tab=info"
  deriving stock (Show, Eq, Generic)
  deriving anyclass Router
```

The router is *reversible* — `prettyRoute` re-serialises any route back to a URL:

```haskell
prettyRoute (Product (Capture 42) (QueryParam (Just "info")))
-- "/product/42?tab=info"
```

> **Note:** The generic parser is first-match, so declare more specific constructors before more general ones (e.g. `DocsPage (Capture "slug" MisoString)` before `Docs`). This site's `Route` does exactly that.

## Defining a Router manually

```haskell
data Route = Product Int

instance Router Route where
  routeParser = routes
    [ Product <$> (path "product" *> capture) ]
  fromRoute (Product n) =
    [ toPath "product", toCapture n ]
```

## Subscribing to URI changes

`routerSub` listens to `popstate` events and delivers the parsed route (or a `RoutingError`) to `update`:

```haskell
app = (component m u v) { subs = [ routerSub HandleRoute ] }

update = \case
  HandleRoute (Right Index) -> page .= HomePage
  HandleRoute (Right About) -> page .= AboutPage
  HandleRoute (Left _)      -> page .= NotFound
```

`uriSub` is the lower-level variant — it delivers the raw `URI` without parsing.

## Navigating programmatically

```haskell
pushURI    uri    -- push a raw URI onto the History stack
pushRoute  route  -- push a typed route (serialised via Router)
replaceURI uri    -- replace the current history entry
back              -- go back one entry
forward           -- go forward one entry
```

## Type-safe links in view

`href_` (from `Miso.Router`) produces a type-safe `href` from any route. Pair it with `onClickPrevent` to navigate client-side while keeping a real link for the browser and crawlers:

```haskell
let product10 =
      Product (Capture 10) (QueryParam Nothing)
in H.a_
     [ href_ product10
     , onClickPrevent (Go product10)
     ]
     [ "Go to product 10" ]
```


---

# HTML & prerendering

> Rendering Views to HTML with ToHtml, static and dynamic prerendering, hydration with miso and hydrateModel.

Source: https://haskell-miso.org/docs/html-and-prerendering/

miso's `View` type doubles as an HTML serialiser via the `ToHtml` class in `Miso.Html.Render`. Build a `View` with the normal DSL and render it to a lazy `ByteString` on the server — or, as this website does, at build time.

```haskell
class ToHtml a where
  toHtml :: a -> L.ByteString

pageHtml :: L.ByteString
pageHtml = toHtml $
  H.div_ [ HP.id_ "root" ] [ "Hello, world!" ]
```

Instances are provided for `View` and `[View]`. Servant users can serve them directly with [servant-miso-html](https://github.com/haskell-miso/servant-miso-html), which provides an `HTML` content type for `View` and `Component` values:

```haskell
import Servant.Miso.Html (HTML)

type Home = "home"
  :> Get '[HTML]
       (Component context props model action)

type About = "about"
  :> Get '[HTML] (View context props model action)

type Contact = "contact"
  :> Get '[HTML] [View context props model action]
```

## Prerendering

Prerendering is delivering HTML from a web server (or a static host) before the client loads and draws anything. It comes in two flavours: *static* prerendering assumes no model state needs to be shared between server and client; *dynamic* prerendering uses `hydrateModel` to share it.

### Static prerendering

miso provides `prerender` and `miso` for static prerendering. Any page can be generated from a `View` with `toHtml`; on the client, pass the matching component to `miso` (instead of `startApp`) so it hydrates the markup rather than redrawing:

```haskell
main :: IO ()
main = prerender defaultEvents $
  (component () noop view)
    { logLevel = DebugPrerender }
  where
    view () = "hello world"
```

With the payload and HTML delivered together, the console shows:

```
[DEBUG_HYDRATE] Successfully prerendered page
```

### Dynamic prerendering

Dynamic prerendering shares model state so the client hydrates from a meaningful initial state rather than a blank model. The `-fssr` flag must be enabled when compiling the server. The `hydrateModel` field is `Maybe (IO model)`: when set, the action runs once at hydration time to produce the initial model; a typical pattern embeds the model as JSON in the response and reads it back through the JS DSL:

```haskell
myComp :: App Model Action
myComp =
  (component defaultModel updateModel viewModel)
    { hydrateModel = Just $ do
        val <- jsg "window" ! "__initialModel__"
        fromJSValUnchecked val
    }

-- On the server, populate
-- window.__initialModel__ alongside
-- the rendered HTML:
serverView
  :: Model
  -> View context props Model Action
serverView m =
  H.div_ []
    [ H.script_ []
        ("window.__initialModel__ = " <> encode m)
    , appView m
    ]
```

When `hydrateModel` is `Nothing` the static `model` field is used instead — equivalent to static prerendering.

## How this site does it

haskell-miso.org has no server. A small `prerender` executable, compiled with vanilla GHC and `-fssr`, walks every route, calls `toHtml` on the root component and writes `index.html` files into `public/`. The WASM bundle then hydrates whichever page was loaded with `misoWithContext` and takes over navigation with `Miso.Router`.


---

# JavaScript EDSL & FFI

> Miso.DSL for jsaddle-style interop, marshalling with ToJSVal / FromJSVal, and the js quasi-quoter.

Source: https://haskell-miso.org/docs/javascript-edsl/

`Miso.DSL` provides a JavaScript DSL inspired by [jsaddle](https://hackage.haskell.org/package/jsaddle) for interacting with the browser from Haskell. It works identically on the WASM and JS backends.

## Key operators

- `(!)` — property access: `obj ! "key"` reads `obj.key`
- `(#)` — method call: `obj # "method" $ args` calls `obj.method(args)`
- `jsg` — access a global JS variable by name
- `jsgf` — call a global JS function by name with arguments

```haskell
-- Read document.body.children.length
document <- jsg "document"
len :: Int <- fromJSValUnchecked =<<
  (document ! "body" ! "children" ! "length")

-- Call console.log("hello")
console <- jsg "console"
console # "log" $ [ "hello" :: MisoString ]
```

## Marshalling

`ToJSVal` converts Haskell values to `JSVal` for passing into JavaScript; `FromJSVal` converts back. `fromJSValUnchecked` throws on failure; `fromJSVal` is the safe `Maybe` variant.

## Inline JavaScript (QuasiQuotation)

`Miso.FFI.QQ` provides the `js` quasi-quoter for embedding JavaScript directly in Haskell source. Any Haskell binding in scope can be interpolated with `${varName}` — miso uses the binding's `ToJSVal` instance to marshal it at runtime.

```haskell
{-# LANGUAGE QuasiQuotes #-}
import Miso.FFI.QQ (js)

update
  :: Action
  -> Effect context props model Action
update = \case
  Log msg -> io_ [js| console.log(${msg}) |]

data Action = Log MisoString
```

### Returning values from JavaScript

The return type is inferred from the call site via `FromJSVal`. Use an explicit annotation or a `do`-binding to drive inference:

```haskell
factorial :: Int -> IO Int
factorial n = [js|
  let x = 1;
  for (let i = 1; i <= ${n}; i++) { x *= i; }
  return x;
|]
```

Haskell variables referenced inside the quoter must be in scope at the splice site; the compiler reports an error if a `${name}` has no binding.

## Miso.FFI

`Miso.FFI` collects typed wrappers for common browser calls: `consoleLog`, `getElementById`, `focus`, `windowInnerWidth`, `addEventListener`, callbacks (`asyncCallback`), `fetch`, `scrollIntoView`, `requestFullscreen` and more. Mutable JS collections live in `Miso.Data.Array`, `Miso.Data.Map` and `Miso.Data.Set`.


---

# Canvas

> 2D canvas support: the Canvas monad, embedding a canvas in the view, drawing commands and animation loops.

Source: https://haskell-miso.org/docs/canvas/

miso has full 2D and 3D canvas support via `Miso.Canvas`. See also the [canvas2d](https://github.com/haskell-miso/canvas2d) example and [three-miso](https://github.com/haskell-miso/three-miso) for Three.js integration.

## The Canvas monad

Drawing commands run in the `Canvas` monad, a `ReaderT` over the raw `CanvasContext2D`:

```haskell
type Canvas a = ReaderT CanvasContext2D IO a
```

## Embedding a canvas in the view

Use the `canvas` smart constructor. It takes an *init* callback (runs once on mount, returns state) and a *draw* callback (runs on every render with the current state). Capture the current model in the draw closure:

```haskell
canvas
  [ HP.width_ "800", HP.height_ "480" ]
  (\_ -> pure ())
  -- init: called once on canvas initialisation
  (\() -> drawScene myModel)
  -- draw: called on each diff
```

`canvas_` is the variant that threads no init state at all.

## Drawing commands

```haskell
drawScene :: Model -> Canvas ()
drawScene model = do
  clearRect (0, 0, 800, 480)
  fillStyle (color (RGB 30 144 255))
  beginPath ()
  arc (400, 240, 50, 0, 2 * pi)
  fill ()
  font "24px sans-serif"
  fillText ("Score: " <> ms (score model), 10, 30)
```

Available primitives include `clearRect`, `fillRect`, `strokeRect`, `beginPath`, `closePath`, `moveTo`, `lineTo`, `arc`, `arcTo`, `fill`, `stroke`, `fillText`, `drawImage`. Style setters: `fillStyle`, `strokeStyle`, `lineWidth`, `font`.

> **Careful:** `Miso.Canvas.color` (builds a `StyleArg`) and `Miso.CSS.color` collide when both modules are imported unqualified. Qualify `Miso.CSS` when also using `Miso.Canvas`.

## Animation loop

For smooth 60 FPS canvas animations, use `rAFSub` from `Miso.Subscription.RAF` instead of a manual `threadDelay` loop. It hooks into `requestAnimationFrame` and delivers a `DOMHighResTimeStamp` each frame:

```haskell
data Action = Tick Double

main :: IO ()
main = startApp defaultEvents
  comp { subs = [ rAFSub Tick ] }
```

## Try it

**Live example: Orbits: rAFSub driving the Canvas monad**

```haskell
data OrbitAction = Frame Double

-- Three planets orbit on a 2D canvas at 60 FPS.
-- rAFSub delivers a requestAnimationFrame timestamp;
-- the draw callback closes over the model.
orbits
  :: Component ctx () Double OrbitAction
orbits = (component 0 update view)
  { subs = [ rAFSub Frame ] }
  where
    update (Frame ms') = this .= ms' / 1000

    view t =
      Canvas.canvas [ HP.width_ "320", HP.height_ "220" ]
        (\_ -> pure ())
        -- init: runs once, no state needed
        (\() -> scene t)
        -- draw: runs after every diff

    scene :: Double -> Canvas.Canvas ()
    scene t = do
      -- a translucent wash instead of clearRect
      -- leaves motion trails
      Canvas.fillStyle (Canvas.color (RGBA 14 13 11 0.24))
      Canvas.fillRect (0, 0, 320, 220)
      let planets =
            [ RGB 255 184 74
            , RGB 240 138 36
            , RGB 226 83 31
            ]
      forM_ (zip [0 ..] planets) $ \(i, planet) -> do
        let phase = t * (1.6 - 0.4 * i) + i * 2.1
            x = 160 + (34 + 30 * i) * cos phase
            y = 110 + (22 + 19 * i) * sin phase
        Canvas.beginPath ()
        Canvas.arc (x, y, 7 - 1.5 * i, 0, 2 * pi)
        Canvas.fillStyle (Canvas.color planet)
        Canvas.fill ()
```


---

# MisoString

> miso's canonical string type: JSString on the client, Text on the server, and how to convert.

Source: https://haskell-miso.org/docs/misostring/

`MisoString` is miso's canonical string type, chosen to minimise copying between the Haskell and JavaScript heaps.

- **JS / WASM backends** — `MisoString` is `JSString`, a direct reference to a JavaScript string; no marshalling cost when passing to the DOM or FFI.
- **Server / vanilla GHC** (`-fssr`) — `MisoString` is `Data.Text`.

Use `MisoString` anywhere you would otherwise reach for `String` or `Text` in a miso application. See `Miso.String` for the full API (it re-exports the underlying module wholesale).

## Converting to MisoString

`ms` (shorthand for `toMisoString`) converts any type with a `ToMisoString` instance:

```haskell
ms "hello"          -- String -> MisoString
ms (42 :: Int)      -- Int    -> MisoString
ms (3.14 :: Double) -- Double -> MisoString
ms myText           -- Text   -> MisoString
```

Instances exist for `String`, strict and lazy `Text`, `ByteString`, `Int`, `Word`, `Double`, `Float` and `Char`.

## Converting from MisoString

`fromMisoString` parses back into another type (throwing on failure); `fromMisoStringEither` is the safe variant:

```haskell
fromMisoString "42"     :: Int     -- 42
fromMisoString "3.14"   :: Double  -- 3.14
fromMisoStringEither s  :: Either String Int
```

## Multiline literals

GHC's `MultilineStrings` extension (9.12+) works directly with `MisoString` — this site uses it for all of its code samples:

```haskell
{-# LANGUAGE MultilineStrings #-}

snippet :: MisoString
snippet = """
  line one
  line two
  """
```

On older compilers, `Miso.String.QQ` provides the `misoString` quasi-quoter for the same purpose.


---

# JSON

> Miso.JSON: a microaeson-style JSON library specialised to MisoString, with generic ToJSON / FromJSON.

Source: https://haskell-miso.org/docs/json/

`Miso.JSON` is a [microaeson](https://hackage.haskell.org/package/microaeson)-inspired JSON library specialised to `MisoString`. On the JS / WASM backends it delegates encoding and decoding to the JavaScript runtime (`JSON.stringify` / `JSON.parse`) for performance; on the server (`ssr`) it uses a pure Haskell implementation. It is used internally by `Miso.Event.Decoder`, `Miso.Fetch` and `Miso.WebSocket`.

## Value

```haskell
data Value
  = Number Double
  | Bool   Bool
  | String MisoString
  | Array  [Value]
  | Object Object
  | Null
```

## Encoding and decoding

```haskell
encode value
-- uses the JS runtime on the client,
-- pure on the server

encodePure value
-- always the pure Haskell implementation

decode s            :: Maybe a
eitherDecode s      :: Either MisoString a
```

## ToJSON / FromJSON

Derive instances via `GHC.Generics`:

```haskell
{-# LANGUAGE DeriveGeneric #-}
import GHC.Generics
import Miso.JSON

data User = User
  { name :: MisoString
  , age  :: Int
  } deriving (Generic)

instance ToJSON User
instance FromJSON User
```

Use `genericToJSON` / `genericParseJSON` with `Options` to customise field and constructor names; `camelTo2` converts `camelCase` to `snake_case`:

```haskell
instance ToJSON User where
  toJSON = genericToJSON defaultOptions
    { fieldLabelModifier = camelTo2 '_' }
```

## Building and parsing objects

```haskell
-- Build
object
  [ "name" .= ms "Alice"
  , "age" .= (30 :: Int)
  ]

-- Parse (inside a withObject
-- callback or event decoder)
withObject "User" $ \o -> User
  <$> o .:  "name"
      -- required field
  <*> o .:  "age"

o .:? "nickname"
-- optional field → Maybe a

o .:! "nickname"
-- optional field, explicit null → Maybe a

p .!= "anon"
-- default for a Maybe parser
```

## Pretty printing

```haskell
encodePretty value
-- indented with defConfig (2-space indent)

encodePretty' config value
-- custom Config
```

## Try it

**Live example: Round-tripping a record with generic instances**

```haskell
data User = User
  { userName :: MisoString
  , userAge  :: Int
  } deriving (Show, Eq, Generic, ToJSON, FromJSON)
    -- generic instances from Miso.JSON

data JsonAction = Edit MisoString

jsonRoundTrip
  :: Component ctx () MisoString JsonAction
jsonRoundTrip = component initial update view
  where
    initial = "{ \"userName\": \"Ada\", \"userAge\": 36 }"

    update (Edit s) = this .= s

    view input =
      H.div_ []
        [ H.textarea_
            [ HP.value_ input
            , HE.onInput Edit
            , textProp "rows" "3"
            ]
        , case eitherDecode input :: Either MisoString User of
            Left err ->
              H.p_ [ HP.class_ "muted" ] [ "✗ ", text err ]
            Right user ->
              H.pre_ []
                [ "✓ "
                , text (ms (show user))
                , "\n"
                , text (encode user)
                ]
        ]
```

## miso-aeson

Prefer aeson? The [miso-aeson](https://github.com/haskell-miso/miso-aeson) package bridges aeson's `ToJSON` / `FromJSON` instances with miso's event decoder and fetch API, so existing instances work without rewriting.

## aeson polyfill

An **aeson polyfill** lives behind an `aeson` cabal flag (`-faeson`): building miso with it defines every operator and class exported by `Miso.JSON` (`ToJSON`, `FromJSON`, `.:`, `.=`, `withObject`, `encode`, `decode`, …) in terms of [Data.Aeson](https://hackage.haskell.org/package/aeson). Existing aeson code — and its instances — works with miso unchanged, with no bridge package and no import churn: keep importing `Miso.JSON` and flip the flag.


---

# Styles

> Three ways to style: the Miso.CSS DSL, inline strings and external stylesheets.

Source: https://haskell-miso.org/docs/styles/

miso does not prescribe a single CSS strategy. Three approaches work out of the box.

## 1. Structured DSL (Miso.CSS)

`style_` takes a list of `Style` values (`(MisoString, MisoString)` pairs). miso manages the individual properties on the `DOMRef`, merging and diffing them efficiently:

```haskell
import qualified Miso.CSS as CSS
import           Miso.CSS.Color (Color (..))

H.div_
  [ CSS.style_
      [ CSS.display "flex"
      , CSS.flexDirection "column"
      , CSS.backgroundColor (RGB 30 30 30)
      , CSS.color (RGB 255 255 255)
      ]
  ]
  []
```

Custom properties can be constructed with the `=:` operator (re-exported from `Miso.Util`):

```haskell
"user-select" =: "none"
```

## 2. Inline string (styleInline\_)

For simple or dynamic style strings, `styleInline_` sets the element's `style` attribute as a raw string:

```haskell
CSS.styleInline_ "display:flex; gap:8px; padding:16px"
```

## 3. External stylesheets

Link external CSS files from the `<head>` via the `styles` field on `Component` (development only — see [Development](https://haskell-miso.org/docs/development/)), or include them in your HTML template directly. This is the most common approach for production apps using Tailwind, Bootstrap, etc. See [miso-ui](https://ui.haskell-miso.org) for a larger example.

## Stylesheets from Haskell

`Miso.CSS` can also express whole stylesheets (`sheet_`, `selector_`) and the `Sheet` constructor of `CSS` lets you attach one to a component during development. Colours come from `Miso.CSS.Color` (`RGB`, `RGBA`, `HSL`, named colours).


---

# Development & debugging

> Dev-time styles and scripts, live reloading in the WASM browser GHCi, and the debug log levels.

Source: https://haskell-miso.org/docs/development/

When developing interactively it is possible to append `styles` and `scripts` to the `<head>` of the page when a component mounts. This is a convenience meant only for development — guard it behind a flag.

```haskell
main :: IO ()
main = startApp defaultEvents app
 where
   app = counter
#ifdef INTERACTIVE
     { scripts =
         [ Src
             "https://code.jquery.com/jquery.min.js"
             (False :: CacheBust)
         ]
     , styles =
         [ Href
             "https://cdn.example.com/bootstrap.min.css"
             (False :: CacheBust)
         ]
     }
#endif
```

## Live reloading

The WASM backend ships a browser-mode GHCi. Run `make watch` in the sample app: `ghciwatch` reloads on save and calls `:main`, and `Miso.Reload.live` (used instead of `startApp` under the `INTERACTIVE` flag) clears the page and remounts. `liveWithContext` does the same for apps that seed a context; when a component's model can be recovered by key it is preserved across reloads.

```shell
$ make watch
# ghciwatch \
#   --after-startup-ghci :main \
#   --after-reload-ghci :main \
#   --watch *.hs \
#   --command 'wasm32-wasi-cabal repl app \
#     -finteractive \
#     --repl-options="-fghci-browser \
#       -fghci-browser-port=8080"'
```

## Debugging

Sometimes things go wrong. Using `onClick` without listening for the `click` event is a common error that cannot be caught statically. Enable `DebugAll` to detect these; currently debugging event delegation and page hydration is supported.

- `DebugHydrate` — warn if the structure or properties of the DOM and the virtual DOM differ during prerendering
- `DebugEvents` — warn if an event cannot be routed to the handler that raised it, or a handler is used for an event nobody listens for
- `DebugAll` — both of the above

```haskell
counter { logLevel = DebugAll }
```


---

# Internals

> How the event queue, scheduler, Waiter, delegation and diffing fit together.

Source: https://haskell-miso.org/docs/internals/

Internally miso uses a global event queue and a scheduler to process all events raised by components throughout the lifetime of an application. Events are processed in FIFO order, batched by the component that raised them.

- **Event queue** — all actions dispatched via a `Sink` (from event handlers, subscriptions or `io` callbacks) are enqueued and drained by the scheduler.
- **Scheduler** — pulls actions off the queue one batch at a time, runs `update` for each, collects the resulting IO and executes it. Rendering (VDOM diff + patch) is triggered after each batch.
- **Waiter** — a synchronisation primitive (`Miso.Concurrent`) that blocks the scheduler thread until new work arrives, avoiding busy-waiting.
- **Event delegation** — rather than attaching listeners to individual nodes, miso attaches a single capture and a single bubble listener to `<body>`. Incoming events are routed through the virtual DOM tree to the matching handler, minimising listener churn when the VDOM is patched.
- **VDOM diffing** — the algorithm in `Miso.Diff` compares old and new `View` trees and emits the minimal set of DOM mutations. Keyed children significantly speed up child-list reconciliation.

## The TypeScript runtime

The DOM operations live in a small TypeScript runtime (`ts/` in the repository, bundled into `js/miso.js`). It implements the drawing context interface that `renderApp` lets you swap — the native backend provides an alternative implementation on top of Lynx's element API. The runtime has a bun test suite with high coverage; `npm test` runs it.


---

# miso native

> Target iOS and Android by driving the Lynx runtime with the same components you write for the web.

Source: https://haskell-miso.org/docs/native/overview/

Your program runs in two JS interpreters at once: the *main thread* (MTS), which owns the drawing facilities, and the *background thread* (BTS), which owns the [native modules](https://lynxjs.org/guide/use-native-modules.html). miso runs on both and keeps them in sync. See [the dual-thread architecture](https://haskell-miso.org/docs/native/dual-thread/).

Miso.Native targets **native mobile devices** by driving the [Lynx](https://lynxjs.org) runtime instead of the browser DOM. The same MVU programming model, Component API, event delegation, and virtual-DOM diffing carry over unchanged from the web; only the element vocabulary differs (view\_ and text\_ instead of div\_ and span\_), and rendering goes through Lynx's [element PAPI](https://lynxjs.org/api/engine/element-api) instead of a browser DOM.

This module is the native analogue of the `miso` / `startApp` entry points: `native` (and `nativeWithContext`) boot a root component onto the Lynx runtime.

## Anatomy of a native miso app

Keep scrolling and the phone comes apart into the dual-thread architecture that runs miso on iOS and Android.

A miso app on your phone.

It all lives in one iOS process.

Lynx hosts two JavaScript interpreters: the main thread renders, the background thread thinks.

Each interpreter loads the same bundle: JavaScript, CSS, assets.

And inside the JS: two GHC runtimes, one application, one miso.

## Enabling native

The native backend is gated behind the `native` cabal flag. It must be enabled to bring `Miso.Native` and the `Miso.Native.*` element / event / FFI modules into scope (build with `-fnative`). Web / WASM builds are unaffected — all cross-thread machinery lives behind the `NATIVE` CPP guard.

```shell
$ nix develop github:dmjio/miso#native
$ cabal build -f native \
    --with-compiler=javascript-unknown-ghcjs-ghc \
    --with-hc-pkg=javascript-unknown-ghcjs-ghc-pkg
```

The JavaScript output is bundled for Lynx with [rspeedy](https://lynxjs.org/rspeedy) and loaded by the Lynx Explorer app or your own iOS / Android shell. The [miso-lynx](https://github.com/haskell-miso/miso-lynx) repository has the tooling, and [miso-lynx-gallery](https://github.com/haskell-miso/miso-lynx-gallery) a gallery of native components.

## Building a bundle with Nix

miso's flake exports everything needed to produce a `main.lynx.bundle` reproducibly. `miso.lib.${system}.ghcNative` is the GHC-JS package set with `miso-native` preinstalled — `callCabal2nix` your own app into it — and `pkgs.mkLynxBundle` (also exported as `miso.lib.${system}.mkLynxBundle`) turns that JS derivation into a Lynx bundle:

```haskell
{
  inputs.miso.url = "github:dmjio/miso";

  outputs = { miso, ... }:
    let system = "x86_64-linux";
        # or aarch64-darwin, …
        lib = miso.lib.${system};
    in {
      packages.${system}.bundle = lib.mkLynxBundle {
        name = "my-app-bundle";
        jsDrv =
          lib.ghcNative.callCabal2nix "my-app" ./. { };
        exeName = "my-app";
        styles = ./styles.css;
      };
    };
}
```

`nix build .#bundle` then leaves `result/main.lynx.bundle` ready to load in the Lynx Explorer app. For interactive work, `nix develop github:dmjio/miso#native` provides the GHC-JS compiler (the `ghcNative` package set), `rspeedy` and `bun`.

To ship a standalone iOS app, the [miso-lynx-gallery](https://github.com/haskell-miso/miso-lynx-gallery) example includes an `ios/` folder: copy the bundle the Nix derivation produced (the `/nix/store` output symlinked at `./result`) into the assets in `ios/` and build with Xcode. See [miso-lynx-gallery](https://github.com/haskell-miso/miso-lynx-gallery) for more information.

## Gallery

The UI stack miso drives natively, in the flesh — screens from Lynx's example apps. The [miso-lynx-gallery](https://github.com/haskell-miso/miso-lynx-gallery) repository builds a gallery of these components in miso.

![An image card with a like button, built on Lynx](https://haskell-miso.org/assets/lynx/lynx-demo-card.webp)![A two-column waterfall gallery built on Lynx, scrolling](https://haskell-miso.org/assets/lynx/lynx-demo-gallery.webp)![A swiper carousel with a page indicator, built on Lynx](https://haskell-miso.org/assets/lynx/lynx-demo-swiper.webp)

*Screens from the [Lynx](https://lynxjs.org) examples (CC BY 4.0) — see [haskell-miso/miso-lynx-gallery](https://github.com/haskell-miso/miso-lynx-gallery) for the miso versions.*

## In this section

- [The dual-thread architecture](https://haskell-miso.org/docs/native/dual-thread/) — BTS vs MTS, what crosses the boundary, the instant first frame.
- [Static mounting](https://haskell-miso.org/docs/native/static-mounting/) — why constructors cross threads as static pointers.
- [Effects, subscriptions and threads](https://haskell-miso.org/docs/native/effects-and-threads/) — `runOnBG`, `runOnMain` and guarding subs.
- [Main-thread events](https://haskell-miso.org/docs/native/main-thread-events/) — low-latency `*Main` handlers.
- [Main-thread-local state](https://haskell-miso.org/docs/native/main-thread-state/) — `MainThreadRef` and `eachFrame`.
- [Platform APIs](https://haskell-miso.org/docs/native/platform-apis/) — which APIs exist on which thread.
- [A minimal native component](https://haskell-miso.org/docs/native/minimal-component/) — the counter, natively.


---

# The dual-thread architecture

> Lynx runs your app on a background thread and a main thread; here is how miso maps onto both.

Source: https://haskell-miso.org/docs/native/dual-thread/

Lynx runs your application across **two threads**, and miso maps onto both:

- **BTS** — the *background thread* ("background thread script"). This is where your application *logic* lives. Everything runs here **by default**: the `update` function, event handling, `Effect` scheduling and *all* virtual-DOM diffing.
- **MTS** — the *main thread* ("main thread script"). This thread owns the actual element tree and *rendering*. It is where the pixels land. It is also available as a low-latency escape hatch for performance-critical event handling (see [Main-thread events](https://haskell-miso.org/docs/native/main-thread-events/)).

The **same Haskell bundle runs on both threads**; the native runtime selects the BTS or MTS drawing context per thread from a global flag, so there is no renderer to register — `native` starts the app directly. The guiding principle: **everything originates on the BTS**. The MTS is a rendering surface that the BTS drives across the thread boundary.

## Knowing which thread you are on

Lynx builds the bundle with rspeedy, which compiles the sources *twice*, once per thread, inlining a compile-time constant (`__BACKGROUND__`) that distinguishes the two. That constant surfaces in Haskell as three top-level `Bool`s in `Miso.Runtime` (re-exported from `Miso`):

- `mts` — `True` when this execution context is the Lynx main thread.
- `bts` — `True` when this context is the Lynx background thread.
- `web` — `True` for a plain web / WASM build (neither Lynx thread).

Exactly one is `True` and the value is invariant for the lifetime of a JS context, so the runtime computes it once and caches it. Runtime code branches on `mts` / `bts` to decide where work runs (e.g. the scheduler suppresses the paint step on the MTS, which keeps only a read-only model replica).

## What crosses the thread boundary, and how

Because logic (BTS) and rendering (MTS) live on different threads, miso synchronises them by shipping messages across the boundary. This is largely invisible, but understanding it explains the API constraints below.

- **Initial draw** — the very first draw happens **on the MTS itself**, and does **not** rely on the BTS diffing a tree and transferring patches. The root component is booted from a `StaticPtr` (via `native`), so the MTS reconstructs it from the pointer's `StaticKey` alone and renders the first frame locally (Lynx's instant first frame). Only *after* this does the cross-thread patch protocol take over: every subsequent diff runs on the BTS and ships patches to the MTS.
- **Subsequent component mounts** — when the BTS `view` mounts a child, that mount is synchronised to the MTS asynchronously using *static mounting*: the child is wrapped in a `static` pointer so only its `StaticKey` — not a closure — crosses the boundary. See [Static mounting](https://haskell-miso.org/docs/native/static-mounting/).
- **State synchronisation** — the BTS owns the shared model and ships it to the MTS as it changes (JSON-serialised, hence the `ToJSON` / `FromJSON` constraints on native mounting combinators), so main-thread `*MainWith` handlers observe an eventually-consistent copy. A child's initial props ride the static-mount payload, but props and the global context are **not** re-synced on later changes: after the first frame they stay background-thread-only (matching ReactLynx).
- **Events** — events raised on the MTS are, by default, forwarded to the BTS where `update` runs. Cross-thread handlers are carried as an `EventHandler` embedded with `event . static (…)` so the peer thread can rebuild the handler from its `StaticKey`.

## The lifecycle, in sequence

*The dual-thread `Component` initialization and lifecycle. The `runOnBG` / `runOnMain` effects and the `on` / `onMain` handlers (highlighted) are how work hops between the threads.*

## First-frame rendering (instant first frame)

The MTS painting frame one itself is Lynx's *instant first frame*: the user sees UI without waiting for a background render and patch round-trip. Meanwhile the BTS boots the *same* root and builds the identical virtual-DOM tree in lockstep — with **deterministic nodeId parity**, so both threads address the same elements — but **suppresses its own create-patches** for that first frame, since the MTS already painted them. A single global `initialDraw` latch governs this on both threads; `native` clears it once the whole root mount has finished.

After that handover the responsibilities are fixed, mirroring ReactLynx: the **BTS is the sole diff / paint authority** — it runs `update`, diffs and ships patches — while the **MTS only applies those patches** (and runs main-thread scripts / handlers). The MTS never diffs or repaints from the scheduler again; this is why the shared model is BTS-owned and why nothing you do on the MTS should try to redraw declaratively.


---

# Static mounting

> Component constructors cross the thread boundary as static pointers: mountStatic, vcomp and VCompStatic.

Source: https://haskell-miso.org/docs/native/static-mounting/

Because component constructors, event handlers and effects may need to be reconstructed on the *other* thread, native miso threads them across the boundary as `static` pointers rather than closures. This requires the `StaticPointers` language extension.

The root component is mounted with `mountStatic` wrapped in `static`:

```haskell
{-# LANGUAGE StaticPointers #-}
module Main where

import Miso
import Miso.Native

main :: IO ()
main = native nativeEvents (static (mountStatic app))
```

Child components are embedded in a `view` the same way, with `vcomp`:

```haskell
view _ =
  view_ []
    [ vcomp_ (static (mountStatic child)) ]
```

> **Careful:** **Static-pointer limitation.**A `static` form may only close over *top-level, closed* bindings — it cannot capture local variables. This is why component constructors and main-thread handlers are supplied as references to top-level definitions, with any runtime data (props, decoded event payloads) shipped separately as serialised values rather than captured in a closure.

## VCompStatic

`VCompStatic` is the `View` constructor behind `vcomp`. Unlike `VComp` it carries a `StaticPtr` to its component constructor, giving the mount a stable, cross-thread-resolvable identity (a `StaticKey`) instead of relying on a manually-supplied `Key`. This is what lets the MTS independently reconstruct a mirror of a component mounted on the BTS, including ones mounted after the initial frame, and is also how actions dispatched from a main-thread handler get routed back to the correct component on the BTS.

The `StaticKey` itself serves as the mount's identity, so there is no need for `(+>)` or a manual key — use `vcomp` (or `vcomp_` when the child takes no props) together with `mountStatic` to build a `VCompStatic`. `mountStatic` accepts components with props directly; for a context-reading child, mount `comp { useContext = True }`.

> **Note:** Under `NATIVE`, `(+>)`, `mount_` and `mountWithProps_` build a `VComp` with no `StaticKey`. A component mounted that way as part of the *initial* frame is fine, but if it is mounted *later* — inside a list or behind a conditional — the MTS never registers a mirror for it, and any main-thread handler inside that subtree silently fails to dispatch. Use `vcomp` with `mountStatic` for anything that may mount after the first frame.


---

# Effects, subscriptions and threads

> runOnBG / runOnMain dispatch an action to the thread that should handle it; subs run on both threads unless guarded.

Source: https://haskell-miso.org/docs/native/effects-and-threads/

Because an `IO` closure can't cross the thread boundary (only JSON-serialised actions can), cross-thread work is expressed as *dispatching an action* to the thread that should handle it. Two combinators do this:

- `runOnBG action` — run `action`'s `update` on the **background** thread (BTS). Used by a main-thread event handler that needs to change shared state, since the BTS solely owns the model.
- `runOnMain action` — run `action`'s `update` on the **main** thread (MTS). Used by a BTS effect that needs an imperative main-thread operation (see `Miso.Native.MainThread`).

Each ships only the given action to the target thread (or dispatches it locally when already there), where its `update` runs exactly once. Sibling effects in the current `update` are unaffected, and nothing is double-executed. Off the native runtime both are an ordinary local dispatch, equivalent to `issue`.

## Subscriptions and threads

A `Sub` is dynamic — it is just a `Sink action -> IO ()` run in a forked thread — and a component's subs are started on **every thread it mounts on**. So a sub runs on **both the BTS and the MTS** (once each), and each copy dispatches into its own thread's scheduler.

Because a sub is ordinary runtime IO — unlike a `static` event handler, whose thread is fixed at compile time — it selects its own thread at runtime with the `mts` / `bts` booleans. This is the dynamic analogue of a handler's `*Main` variant:

```haskell
-- background-only: open the socket once, feed the model
wsSub sink = when bts (websocketConnect "wss://…" sink)

-- main-thread-only: drive an imperative animation
animSub _ = when mts (eachFrame step)
```

> **Careful:** **Guard anything that must be single-owned.**Without a `bts` / `mts` gate a stateful sub double-runs — two websocket connections, a timer ticking on both threads — so pin such subs to one thread. The no-op fork on the other thread returns immediately.


---

# Main-thread events

> Per-handler thread affinity: \*Main variants run synchronously on the MTS for gesture- and scroll-linked work.

Source: https://haskell-miso.org/docs/native/main-thread-events/

**Thread affinity is per-handler, not per-event-name.**Any given event can be handled on *either* thread; the choice is made at each handler, so the same event (say `tap`) may run on the BTS for one element and the MTS for another. The **default is the BTS** — a plain `onTap` handler runs on the background thread. Opting a handler into the MTS is explicit; nothing runs on the main thread unless you ask for it.

By default an event handler runs on the BTS: the event is forwarded from the MTS, `update` runs on the BTS, the model changes, and the resulting diff is shipped back to the MTS to paint. That round-trip is fine for most interactions but adds latency for gesture- and scroll-linked animation.

For those cases, handlers have **\*Main-suffixed variants** (e.g. `onTapMain`, `onTouchMoveMain`) that run **synchronously on the MTS** — no VDOM diff, no patches, no BTS round-trip. Such a handler is *imperative*: it mutates the target element directly through the helpers in `Miso.Native.MainThread` (e.g. `setStyleProperty`). The `*MainWith` variants additionally hand the handler the current model and the target `DOMRef`.

Because a main-thread handler must be reconstructed on the MTS, it is an `EventHandler` embedded with `event . static` — so main-thread event handlers require `StaticPointers`:

```haskell
{-# LANGUAGE StaticPointers #-}

view _ =
  view_ [ event (static (onTapMain HandleTap)) ] []
```

The same `static` capture limitation applies: an `onTapMain` handler refers to a top-level action / function; runtime data reaches the handler via the decoded event payload, not a captured closure.

## The generic primitives: on and onMain

The per-element `on*` / `on*Main` helpers are sugar over two combinators, and the *same* `(eventName, decoder, toAction)` works with either — that is how one event is captured on whichever thread you choose, per handler:

- `on name decoder toAction` → a plain `Attribute` that runs on the **BTS**. No `static`: a background handler is reconstructed nowhere else, so it may close over the enclosing `view`.
- `onMain name decoder toAction` → an `EventHandler` that runs on the **MTS**, embedded with `event . static`.

```haskell
-- same `tap` event, one handler per thread:

-- on the BTS
view_
  [ on "tap" emptyDecoder (\_ _ _ -> Grow) ]
  children

-- on the MTS
view_
  [ event (static (onMain "tap" emptyDecoder onTapMain)) ]
  children
```

The `Attribute`-versus-`EventHandler`+`static` split *is* the mechanism: only the main-thread handler has to cross to the MTS by `StaticKey`, which is why `onMain` (and every `*Main` helper) needs `StaticPointers` while `on` does not. `onMainWithOptions` exposes `Phase` / `Options` for the MTS variant, mirroring `onWithOptions`.

## Reaching the model (and why it is passed, not captured)

A static main-thread handler *cannot* close over the model, props or context from the enclosing `view` — those are local bindings, which `static` forbids. So rather than capture them, the `*MainWith` variants **pass the model as an argument** to the handler, giving imperative MTS code the state it needs without a BTS round-trip. Note this is the main thread's own copy of the model: it is populated on the MTS eventually consistently from the BTS, so a handler may observe a value slightly behind the latest BTS state.

### Props and context are not on the main thread

Unlike the model, a component's props and the app-global context are **not** mirrored to the MTS at all (matching ReactLynx, where React state is background-thread-only). They live solely on the BTS; the MTS keeps only its boot values, so `getProps` / `getContext` inside a main-thread handler would read stale data. If a main-thread handler needs a prop or context value, fold it into the model or carry it in the dispatched action payload.

### Ownership caveat

A property you drive imperatively from the MTS must not *also* be written declaratively by the BTS `view` for the same element: both threads write the shared element tree through the same PAPI with no arbitration, so one will clobber the other. Keep a single owner per `(element, property)` — typically compositor properties like `transform` / `opacity` that the view leaves alone.


---

# Main-thread-local state

> MainThreadRef: an IORef for state that lives only on the MTS, paired with eachFrame for vsync-coalesced animation.

Source: https://haskell-miso.org/docs/native/main-thread-state/

A main-thread handler is imperative and must not write the BTS-owned model: shared state changes belong on the background thread, so dispatch them with `runOnBG`. But gestures and scroll-linked animation often need mutable state that lives *only* on the MTS — the current drag offset, a fling velocity, whether a follow loop is active. For that, use a `MainThreadRef`, a thin `IORef` wrapper for main-thread-only state (the analogue of ReactLynx's `MainThreadRef`):

```haskell
dragRef :: MainThreadRef Int
dragRef = mainThreadRef 0
{-# NOINLINE dragRef #-}
```

`mainThreadRef` allocates the underlying cell as a CAF via `unsafePerformIO`, so **every top-level binding needs its own NOINLINE pragma** — otherwise GHC may inline the CAF and split the state into independent copies. Reads and writes (`readMainThreadRef` / `writeMainThreadRef` / `modifyMainThreadRef`) are ordinary `IORef` operations — safe without atomics because the MTS is single-threaded — and `modifyMainThreadRef_` takes a `State a ()` so you can drive updates with the `Miso.Lens` operators.

## eachFrame

It pairs with `eachFrame` for a vsync-coalesced animation loop: read the latest gesture state from the ref, imperatively paint at most once per frame (via `setStyleProperty` / `setStylePropertyTransform`), and stop by returning `False` when the gesture ends.

```haskell
followSub :: Sub Model Action
followSub _ = when mts $ eachFrame $ \_ts -> do
  offset <- readMainThreadRef dragRef
  setStylePropertyTransform card
    [ CSS.translateX (CSS.px offset) ]
  readMainThreadRef dragging
  -- keep looping while a drag is active
```


---

# Platform APIs and thread restrictions

> Native modules are BTS-only, main-thread element ops are MTS-only; guard with mts / bts.

Source: https://haskell-miso.org/docs/native/platform-apis/

Mirroring Lynx ("not all APIs exist on both threads"), miso's native APIs are split by thread, and calling one from the wrong thread fails at runtime — the type system does not catch it, so guard with `mts` / `bts` when code may run on either thread. Neither module is re-exported from `Miso.Native`; import it directly.

## Native modules (BTS-only)

`Miso.Native.Module` wraps Lynx's global [NativeModules](https://lynxjs.org/guide/use-native-modules.html) (platform capabilities: storage, clipboard, device info, …). `callNativeModule` invokes a void-returning method and `callNativeModuleWith` a callback method whose result is decoded via `FromJSON`. `NativeModules` exists **only on the BTS**:

```haskell
callNativeModule "NativeLocalStorageModule" "setStorageItem"
  [ String "key", String "value" ]
```

`update` runs on the BTS by default, so this just works there; from a main-thread handler, hop to the BTS first with `runOnBG`. On the MTS the module is `undefined` and the call logs a console error.

## Main-thread element ops (MTS-only)

The imperative helpers in `Miso.Native.MainThread` (`setStyleProperty` etc.) and the element PAPI they call exist **only on the MTS**; on the BTS they no-op. Drive them from a `*Main` handler or via `runOnMain`.

| API | BTS | MTS |
| --- | --- | --- |
| `update` (default handlers, effects) | ✓ | via `runOnMain` |
| `Miso.Native.Module` (NativeModules) | ✓ | ✗ (undefined) |
| `Miso.Native.MainThread` (element ops, `eachFrame`) | ✗ (no-op) | ✓ |
| `MainThreadRef` | — | ✓ |
| `Sub` | ✓ (guard with `bts`) | ✓ (guard with `mts`) |


---

# A minimal native component

> The counter, written against Miso.Native's element vocabulary.

Source: https://haskell-miso.org/docs/native/minimal-component/

The web counter from [Your first Component](https://haskell-miso.org/docs/your-first-component/) translates line for line. Only the elements and the entry point change.

```haskell
{-# LANGUAGE StaticPointers #-}
module Main where

import Miso
import Miso.Native

data Action = Increment | Decrement

app :: Component () () Int Action
app = component 0 update view

update
  :: Action
  -> Effect () () Int Action
update = \case
  Increment -> this += 1
  Decrement -> this -= 1

view
  :: Int
  -> View () () Int Action
view m =
  vfrag
    [ view_ [ onTap Increment ] [ text_ [] [ "+" ] ]
    , text_ [] [ text (ms (show m)) ]
    , view_ [ onTap Decrement ] [ text_ [] [ "-" ] ]
    ]

main :: IO ()
main = native nativeEvents (static (mountStatic app))
```

`view_` and `text_` come from `Miso.Native.Element`; `onTap` from the element's event module. `nativeEvents` is the Lynx equivalent of `defaultEvents`. Everything else — `component`, `Effect`, lenses, `vfrag` — is exactly the web API.

More information on how to use miso natively is available on GitHub: [haskell-miso/miso-lynx](https://github.com/haskell-miso/miso-lynx) (with a gallery app) and the [sphynx](https://github.com/haskell-miso/sphynx) project demonstrating cross-thread communication.


---

# Thinking in miso

> A guided walk-through: from a mockup to a working application, the miso way.

Source: https://haskell-miso.org/docs/thinking/overview/

miso can change how you think about the designs you look at and the apps you build. When you build a UI with miso you will first describe its *state* as data, then write a pure function from that state to the screen, and finally name the *events* that move the state forward. This guide walks through that process by building a small bookmarks manager.

## Start with the mockup

Imagine we already have a JSON endpoint and a mockup from a designer. Here it is — except this "mockup" is already the finished application, running (the endpoint is mocked with a local list):

Loading bookmarks…

*The mockup, live. Search, filter by tag, click a row for the detail pane — everything this guide builds, in ~60 lines.*

and some data:

```
[ { "id": 1
  , "title": "miso on GitHub"
  , "url": "https://github.com/dmjio/miso"
  , "tags": ["haskell"]
  }
, { "id": 2
  , "title": "Lynx docs"
  , "url": "https://lynxjs.org"
  , "tags": ["mobile"]
  }
, { "id": 3
  , "title": "Elm architecture"
  , "url": "https://guide.elm-lang.org"
  , "tags": ["haskell"]
  }
]
```

## The four steps

1. [**Design the model**](https://haskell-miso.org/docs/thinking/model/) — write down the minimal state the UI needs, and nothing that can be computed from it.
2. [**Break the UI into views and components**](https://haskell-miso.org/docs/thinking/components/) — decide what is a plain view function and what deserves its own `Component`, and where each piece of state lives.
3. [**Name the actions and write update**](https://haskell-miso.org/docs/thinking/update/) — describe how the model evolves and keep IO at the edges.
4. [**Connect the pieces**](https://haskell-miso.org/docs/thinking/data-flow/) — props down, mail up, context around; then prerender, route and ship.

## The mindset in three sentences

- **State is data.** Your whole UI at any instant is a plain Haskell value with an `Eq` instance.
- **The view is a function.** `view :: context -> props -> model -> View` — no hidden state, no mutation, nothing to keep in sync.
- **Change is a fold.** Every event is an `action`; `update` folds it into the model and *schedules* any IO. Results come back as more actions.

If you have written Elm, this will feel like home. If you come from React, notice that there are no hooks to order, no dependency arrays and no stale closures — the model is the only state and it is always current. For the hook-by-hook translation, see [miso vs. React](https://haskell-miso.org/docs/thinking/miso-vs-react/).


---

# Step 1: Design the model

> Find the minimal representation of state; derive everything else in view.

Source: https://haskell-miso.org/docs/thinking/model/

The model is the single source of truth. The goal is to make it *minimal*: store what the UI cannot recompute, and compute everything else inside `view`.

## List everything the UI shows

- The list of bookmarks from the server
- The search text the user typed
- The selected tag filter
- The bookmarks that match the search and the filter
- The count next to each tag
- Which bookmark is expanded in the detail pane
- Whether we are still loading, or something failed

Now ask three questions of each item. Does it change over time? Can it be computed from something else? Is it passed in from a parent?

- The **matching bookmarks** and the **tag counts** are computed from the list, the query and the filter — *not* state.
- Loading and failure are **states of the list itself**, so model them as one type rather than three booleans.

## Write it down

```haskell
data Model = Model
  { _bookmarks :: Remote [Bookmark]
    -- what the server said (or hasn't yet)
  , _query :: MisoString
    -- search text
  , _tagFilter :: Maybe Tag
    -- Nothing = all
  , _selected :: Maybe BookmarkId
    -- expanded row
  } deriving (Eq, Generic)

data Remote a
  = Loading
  | Failed MisoString
  | Loaded a
  deriving (Eq, Generic)

data Bookmark = Bookmark
  { bookmarkId :: BookmarkId
  , title      :: MisoString
  , url        :: MisoString
  , tags       :: [Tag]
  } deriving (Eq, Generic, FromJSON)

makeLenses ''Model
```

Four fields. Everything the mockup shows can be produced from them:

```haskell
visible :: Model -> [Bookmark]
visible m =
  [ b | Loaded bs <- [m ^. bookmarks], b <- bs
      , matches (m ^. query) b
      , maybe True (`elem` tags b) (m ^. tagFilter) ]

tagCounts :: [Bookmark] -> [(Tag, Int)]
tagCounts = ...
```

> **Tip:** Derived values are just functions — call them from `view`. miso only re-renders when the model changed (its `Eq` instance decides), and the virtual DOM diff makes redraws cheap. Reach for memoisation only when a profiler tells you to.

## Sum types beat booleans

`Remote` makes the impossible states ("loaded *and* failed") unrepresentable, and `view` is forced to handle every case with a `case` expression. The same idea applies to modes (`Viewing | Editing Draft`), wizards (one constructor per step) and forms (`Either Errors Valid`).

## Eq is a feature

Every model needs an `Eq` instance. Derive it. It is what lets miso skip a render when nothing changed, and it is what makes tests trivial: `update` is a pure `RWS` so `runEffect` gives you the new model to compare against an expected value.

Next: [break the UI into views and components](https://haskell-miso.org/docs/thinking/components/).


---

# Step 2: Views and components

> Most of your UI should be plain view functions. Reach for a Component when a piece needs its own state, subs or lifecycle.

Source: https://haskell-miso.org/docs/thinking/components/

In miso there are two ways to split a UI: **view functions** (any function returning a `View`) and **components** (a `Component` with its own model, update and lifecycle). Reach for the first by default.

## Draw the boxes

```
BookmarksApp  (Component — owns the Model)
├── searchBar      (view: query, onInput)
├── tagSidebar     (view: tag counts, tag)
├── bookmarkTable  (view function)
│   └── bookmarkRow (view, keyed by id)
├── detailPane     (view function)
└── "add" +> addBookmarkForm
      (Component — owns its draft,
       validation and submit state)
```

*Boxes are functions. Only two of them are components.*

## When is something a Component?

A `Component` costs a little ceremony (its own model and action type, a key) and buys isolation. Make one when a piece of UI:

- **owns state nobody else needs** — the add form's draft and validation errors are irrelevant to the table;
- **needs subscriptions or lifecycle hooks** — a clock, a websocket, a third-party widget initialised in `mount`;
- **is reused with different props** — the same `avatar` component mounted for each user;
- **should re-render independently** — its model changes often while the parent's does not.

Otherwise write a function. `bookmarkRow :: Bookmark -> View ctx props Model Action` is simpler than a component, is trivially testable, and re-renders as part of its parent.

```haskell
bookmarkRow
  :: Maybe BookmarkId
  -> Bookmark
  -> View ctx props Model Action
bookmarkRow selected b =
  H.tr_
    [ key_ (bookmarkId b)
      -- stable identity in the list
    , HP.classList_
        [ ("selected", isSelected) ]
    , HE.onClick (Select (bookmarkId b))
    ]
    [ H.td_ [] [ text (title b) ]
    , H.td_ [] [ text (MS.intercalate ", " (tags b)) ]
    ]
  where
    isSelected = selected == Just (bookmarkId b)
```

> **Note:** Give list items a `key_`. It keeps the DOM node (and any CSS transition on it) attached to the *same* bookmark when the list is filtered or reordered — see [Keys](https://haskell-miso.org/docs/keys/).

## Where does each piece of state live?

| State | Lives in | Because |
| --- | --- | --- |
| bookmarks, query, filter, selection | `BookmarksApp` model | several views read it; the app owns it |
| the add form's draft & errors | `addBookmarkForm` model | private; nobody else cares until submit |
| the currently selected tag, as seen by the form | props | the form only *reads* it to pre-fill a tag |
| language, theme, current user | context | global; every component may read it |

The rule of thumb: state lives in the **closest common owner** of everything that reads or writes it. Push it up only as far as it needs to go, and pass it down as props.

```haskell
viewApp
  :: Model
  -> View Ctx () Model Action
viewApp m = vcontext $ \ctx ->
  H.main_ []
    [ searchBar (m ^. query)
    , H.div_ [ HP.class_ "columns" ]
        [ tagSidebar
            (m ^. tagFilter)
            (tagCounts (loadedOr [] (m ^. bookmarks)))
        , bookmarkTable (m ^. selected) (visible m)
        , detailPane (selectedBookmark m)
        ]
    , mountWithProps_ "add-form"
        (FormProps (m ^. tagFilter))
        addBookmarkForm
    ]
```

Next: [name the actions and write update](https://haskell-miso.org/docs/thinking/update/).


---

# Step 3: Actions and update

> Actions are the vocabulary of your UI. update folds them into the model and schedules IO at the edge.

Source: https://haskell-miso.org/docs/thinking/update/

An `action` is something that *happened*: the user typed, the server answered, a timer fired. Name actions after events, not after setters, and let `update` decide what they mean.

## The vocabulary

```haskell
data Action
  = Init
    -- mounted: go fetch
  | GotBookmarks (Either MisoString [Bookmark])
  | QueryChanged MisoString
  | TagPicked (Maybe Tag)
  | Select BookmarkId
  | BookmarkAdded Bookmark
    -- mailed up by the form
  deriving (Eq, Show)
```

`QueryChanged` rather than `SetQuery`: the name leaves `update` free to also reset the selection, or later to debounce a request, without renaming anything.

## update is a fold

```haskell
update
  :: Action
  -> Effect Ctx () Model Action
update = \case
  Init ->
    getJSON "/api/bookmarks" []
      (GotBookmarks . Right)
      (GotBookmarks . Left . ms)

  GotBookmarks (Right bs) -> bookmarks .= Loaded bs
  GotBookmarks (Left err) -> bookmarks .= Failed err

  QueryChanged q -> do
    query    .= q
    selected .= Nothing
    -- a new search deselects

  TagPicked t -> tagFilter .= t
  Select bid  -> selected  %= toggle bid

  BookmarkAdded b -> bookmarks %= fmap (b :)
```

Every branch is a small, total function on the model. There is no `await`, no promise chain, no `setState` callback ordering: `getJSON` *schedules* the request and the answer arrives later as `GotBookmarks`, which is handled like any other action.

## IO lives at the edge

- `io` / `io_` for asynchronous work — the default. The scheduler runs it off the update thread and catches exceptions.
- `sync` only for cheap, must-be-ordered reads (a `localStorage` lookup, measuring an element).
- `mount = Just Init` to kick things off when the component appears; `unmount` to clean up.
- Long-lived sources are [subscriptions](https://haskell-miso.org/docs/subscriptions/) — a websocket, `rAFSub`, `routerSub` — not effects.

### Example: debouncing the search

Because subs can be started and stopped from `update`, a debounce is a tiny sub rather than a library:

```haskell
QueryChanged q -> do
  query .= q
  stopSub "debounce"
  startSub "debounce" $ \sink -> do
    threadDelay 250000
    sink (Search q)
```

## Testing

`update` is an `RWS` and `view` is a function, so both are testable without a browser: run `update` on a model, compare the resulting model with `==`, and render `view` to HTML with `toHtml` to assert on markup.

Next: [connect the pieces and ship](https://haskell-miso.org/docs/thinking/data-flow/).


---

# Step 4: Connect the pieces and ship

> Props down, mail up, context around, PubSub sideways — then routing, prerendering and mobile.

Source: https://haskell-miso.org/docs/thinking/data-flow/

So far data has flowed *down*: the app owns the model, view functions read it, the form receives props. Real apps also need to send things *up* and *sideways*. miso gives you a small set of tools; pick the least powerful one that works.

## The toolbox

| You need to… | Use | Notes |
| --- | --- | --- |
| give a child read-only data | `mountWithProps_` | synchronous; child re-renders when props change; `onPropsChanged` to react |
| tell the parent something happened | `mailParent` | asynchronous JSON message; parent's `mailbox = checkMail …` |
| share something with the whole tree | context (`modifyContext`) | theme, language, session; opt in with `useContext` |
| notify components that don't know each other | `Miso.PubSub` | topics; `publish` / `subscribe` |
| poke a specific component | `mail componentId` | ids come from `ask` inside `Effect` |

## Inverse data flow: the form tells the app

When the add form is submitted it does not reach into the app's model — it can't. It mails its parent, and the parent decides:

```haskell
-- in addBookmarkForm's update
Submit -> do
  draft <- use form
  case validate draft of
    Left errs -> errors .= errs
    Right b   -> do
      mailParent b
      -- b has a ToJSON instance
      form .= emptyDraft

-- in the app
app = (component m update viewApp)
  { mailbox = checkMail BookmarkAdded MailError
  , mount = Just Init
  }
```

The child stays reusable (it knows nothing about bookmarks lists) and the app stays in control of its own state.

## Routing

Make the selected bookmark a URL: `/bookmarks/2`. Derive a `Router` from a sum type, subscribe with `routerSub` and treat navigation as just another action — see [Routing](https://haskell-miso.org/docs/routing/). Links stay real `<a href>` elements (crawlable, middle-clickable) with an `onClickPrevent` that pushes the route.

## Prerender and hydrate

Because `view` is pure, the same code renders HTML on a server or at build time (`toHtml`), and the client *hydrates* it with `miso` instead of redrawing. Users see content before the WASM loads; search engines see everything. See [HTML & prerendering](https://haskell-miso.org/docs/html-and-prerendering/).

## Take it to mobile

Nothing above mentioned the DOM. Swap `Miso.Html.Element` for `Miso.Native.Element`, `startApp` for `native`, and the model, update, actions and data flow carry over to iOS and Android through Lynx — see [miso native](https://haskell-miso.org/docs/native/overview/).

## Recap

1. Model: minimal state, derived values in `view`, sum types over booleans.
2. Views by default; components for owned state, subs and lifecycle. Keys on lists.
3. Actions are events; `update` is a pure fold; IO is scheduled at the edge.
4. Props down, mail up, context around, PubSub sideways. Route, prerender, ship.

That is all of miso's architecture. The rest is the [API](https://haskell-miso.org/docs/).


---

# miso vs. React

> A translation guide for React developers: which hooks map onto which miso constructs, and which names are false friends.

Source: https://haskell-miso.org/docs/thinking/miso-vs-react/

If you come from React, most of your instincts carry over: components, props, context, fragments, keys and a virtual DOM all work the way you expect. The *hooks* do not — their jobs exist in miso, but they are done by different constructs. Below, the **false friends** (same job, different shape) and the **friends** (same name, same idea).

## False friends

Each of these hooks solves a problem miso solves elsewhere:

| React | miso | The difference |
| --- | --- | --- |
| `useState` | the `model` + `Miso.Lens` | one model per component; lenses are the getters / setters; updates are pure |
| `useEffect` | `Effect` | IO is *scheduled* from `update`, results return as actions; no dependency arrays |
| `useReducer` | `update` | not opt-in: every component *is* a reducer |
| `useRef` | `onCreated` / `onCreatedWith` | lifecycle hooks hand you the `DOMRef` directly |

### useState → the model and Miso.Lens

There is no per-hook state cell. A component's state is its `model` — one plain Haskell value — and `Miso.Lens` generates the getter / setter pairs. Writes happen in exactly one place (`update`), purely, with the lens operators:

```haskell
data Model = Model { _count :: Int }
  deriving (Show, Eq)

count :: Lens Model Int
count = lens _count $ \m x -> m { _count = x }

update = \case
  Increment -> count += 1
  Reset     -> count .= 0
```

Because the setter is not a function you thread through your render, there are no stale closures and no batching surprises — `view` always sees the current model.

### useEffect → Effect

`update` runs in the `Effect` monad. IO is never performed inline; it is *scheduled* with `io` / `io_` and its result comes back as another action, folded in like any other:

```haskell
update = \case
  FetchUser uid ->
    io (GotUser <$> lookupUser uid)
  GotUser u ->
    user .= u
```

No dependency arrays, no effect re-run rules, no cleanup functions to remember: long-running concerns are [subscriptions](https://haskell-miso.org/docs/subscriptions/), which stop automatically when the component unmounts. See [Effects](https://haskell-miso.org/docs/effects/).

### useReducer → update

The closest cousin — except it is not an opt-in pattern. Every miso component is a reducer: the `action` type is your action union, `update` is the reducer and the `model` is the state. [Step 3](https://haskell-miso.org/docs/thinking/update/) of this guide is exactly the `useReducer` mindset, applied everywhere.

### useRef → lifecycle hooks and DOMRef

Where React reaches for `useRef` to hold a DOM node, miso's element [lifecycle hooks](https://haskell-miso.org/docs/view-dsl/) hand the node to you: `onCreatedWith` dispatches an action carrying the `DOMRef` when the element is created (and `onDestroyed` when it goes away):

```haskell
view _ =
  H.canvas_ [ onCreatedWith SetupChart ] []

update = \case
  SetupChart ref ->
    io_ (initChart ref)
```

The ref is an ordinary action payload — store it in the model if you need it later. There is no `.current` escape hatch to mutate around the render cycle.

## Friends

These mean the same thing on both sides of the border:

- **Context** — one global value shared by the whole tree, read without prop-drilling; write it with `modifyContext`. Where React components call the `useContext` hook to subscribe, in miso *any* component can subscribe to context changes by enabling the field of the same name — `useContext = True` — or by mounting with the `mountUseContext` shorthand. See [Context](https://haskell-miso.org/docs/context/).
- **Props** — read-only data a parent passes to a child (`mountWithProps_`); the child re-renders when they change and can react via `onPropsChanged`. See [Props](https://haskell-miso.org/docs/props/).
- **Fragment** — `vfrag` is `<></>`: group siblings without a wrapper element, keyed variants included. See [Fragments](https://haskell-miso.org/docs/fragments/).
- **Keys, components, event delegation, virtual DOM** — miso implements the same architecture internals as React, so [keys](https://haskell-miso.org/docs/keys/) drive reconciliation and events delegate through one root listener, exactly as you are used to.

```haskell
-- subscribe to context changes, two ways:

child = (component m u v)
  { useContext = True }

-- or at the mount site:
view _ =
  H.div_ []
    [ mountUseContext themedBadge ]
```

> **Note:** There are no Rules of Hooks to obey: nothing depends on call order, state is never conditional on a code path, and there is nothing to lint. A component is a value; `view` and `update` are functions.


---

# Examples

> Real applications built with miso: games, browser API demos, integrations and libraries from the haskell-miso organisation.

Source: https://haskell-miso.org/examples/

## Games

- [chess](https://github.com/haskell-miso/chess): The game of chess. Live demo: https://chess.haskell-miso.org/
- [solitaire](https://github.com/haskell-miso/solitaire): Klondike solitaire. Live demo: https://solitaire.haskell-miso.org/
- [tetris](https://github.com/haskell-miso/tetris): The game of Tetris. Live demo: https://tetris.haskell-miso.org/
- [2048](https://github.com/haskell-miso/2048): A 2048 clone. Live demo: https://2048.haskell-miso.org/
- [snake](https://github.com/haskell-miso/snake): A snake clone. Live demo: https://snake.haskell-miso.org/
- [asteroid](https://github.com/haskell-miso/asteroid): The game of Asteroids. Live demo: https://asteroid.haskell-miso.org/
- [plane](https://github.com/haskell-miso/plane): A Flappy Bird clone. Live demo: https://plane.haskell-miso.org/
- [mario](https://github.com/haskell-miso/mario): A Super Mario physics example. Live demo: https://mario.haskell-miso.org/
- [minesweeper](https://github.com/haskell-miso/minesweeper): The classic Minesweeper. Live demo: https://minesweeper.haskell-miso.org/
- [tic-tac-miso](https://github.com/haskell-miso/tic-tac-miso): Tic-tac-toe. Live demo: https://tic-tac-miso.haskell-miso.org/
- [blockout](https://github.com/haskell-miso/blockout): The game of Blockout. Live demo: https://blockout.haskell-miso.org/
- [mahjong](https://github.com/haskell-miso/mahjong): The game of Mahjong. Live demo: https://mahjong.haskell-miso.org/
- [sudoku](https://github.com/haskell-miso/sudoku): The game of Sudoku. Live demo: https://sudoku.haskell-miso.org/
- [slingo](https://github.com/haskell-miso/slingo): The game of Slingo. Live demo: https://slingo.haskell-miso.org/
- [texasholdem](https://github.com/haskell-miso/texasholdem): Texas Hold 'Em poker. Live demo: https://texasholdem.haskell-miso.org/
- [orbital-breakdown](https://gitlab.com/dpwiz/orbital-breakdown): Breakout in space, and every ball is a curveball. Live demo: https://orbital-breakdown.haskell-game.dev/

## Browser APIs

- [canvas2d](https://github.com/haskell-miso/canvas2d): 2D canvas rendering. Live demo: https://canvas.haskell-miso.org/
- [svg](https://github.com/haskell-miso/svg): SVG rendering showcase. Live demo: https://svg.haskell-miso.org/
- [mathml](https://github.com/haskell-miso/mathml): MathML rendering. Live demo: https://mathml.haskell-miso.org/
- [audio](https://github.com/haskell-miso/audio): The \<audio> API. Live demo: https://audio.haskell-miso.org/
- [video](https://github.com/haskell-miso/video): The \<video> API. Live demo: https://video.haskell-miso.org/
- [camera](https://github.com/haskell-miso/camera): The Camera API. Live demo: https://camera.haskell-miso.org/
- [filereader](https://github.com/haskell-miso/filereader): The FileReader API. Live demo: https://file-reader.haskell-miso.org/
- [fileupload](https://github.com/haskell-miso/fileupload): File uploads.
- [drag-and-drop](https://github.com/haskell-miso/drag-and-drop): The Drag-and-drop API. Live demo: https://drag-and-drop.haskell-miso.org/
- [storage](https://github.com/haskell-miso/storage): Local and session storage. Live demo: https://storage.haskell-miso.org/
- [cookies](https://github.com/haskell-miso/cookies): The CookieStore API. Live demo: https://cookies.haskell-miso.org/
- [fetch](https://github.com/haskell-miso/fetch): AJAX requests with fetch. Live demo: https://fetch.haskell-miso.org/
- [websocket](https://github.com/haskell-miso/websocket): A multi-WebSocket example. Live demo: https://websocket.haskell-miso.org/
- [sse](https://github.com/haskell-miso/sse): Server-sent events. Live demo: https://sse.haskell-miso.org/

## Patterns

- [counter](https://github.com/haskell-miso/counter): The simplest possible app. Live demo: https://counter.haskell-miso.org/
- [todo-mvc](https://github.com/haskell-miso/todo-mvc): The classic TodoMVC. Live demo: https://todomvc.haskell-miso.org/
- [router](https://github.com/haskell-miso/router): Client-side routing. Live demo: https://router.haskell-miso.org/
- [props](https://github.com/haskell-miso/props): React-style props. Live demo: https://props.haskell-miso.org/
- [context](https://github.com/haskell-miso/context): The global context. Live demo: https://context.haskell-miso.org/
- [pubsub](https://github.com/haskell-miso/pubsub): Publish / subscribe between components. Live demo: https://pubsub.haskell-miso.org/
- [sampler](https://github.com/haskell-miso/sampler): A sample application for getting started quickly. Live demo: https://sampler.haskell-miso.org/

## Integrations

- [three-miso](https://github.com/haskell-miso/three-miso): Three.js via three.hs. Live demo: https://threejs.haskell-miso.org/
- [aframe](https://github.com/haskell-miso/aframe): A-Frame WebXR scenes. Live demo: https://aframe.haskell-miso.org/
- [chartjs](https://github.com/haskell-miso/chartjs): chart.js charts. Live demo: https://chartjs.haskell-miso.org/
- [c3.js](https://github.com/haskell-miso/c3.js): c3.js charts. Live demo: https://c3js.haskell-miso.org/
- [highlight.js](https://github.com/haskell-miso/highlight.js): highlight.js syntax highlighting. Live demo: https://highlightjs.haskell-miso.org/
- [mathjax](https://github.com/haskell-miso/mathjax): MathJax typesetting. Live demo: https://mathjax.haskell-miso.org/
- [tiptap](https://github.com/haskell-miso/tiptap): The TipTap rich-text editor. Live demo: https://tiptap.haskell-miso.org/
- [supabase-miso](https://github.com/haskell-miso/supabase-miso): Supabase bindings.
- [miso-diagrams](https://github.com/haskell-miso/miso-diagrams): Draw diagrams with miso. Live demo: https://diagrams.haskell-miso.org/

## Libraries & tooling

- [miso.ui](https://github.com/haskell-miso/miso.ui): A component library based on shadcn and Tailwind, built with Basecoat. Live demo: https://ui.haskell-miso.org/
- [miso-tagsoup](https://github.com/haskell-miso/miso-tagsoup): Parse raw HTML / SVG into a View.
- [servant-miso-html](https://github.com/haskell-miso/servant-miso-html): Render miso Views as HTML with servant.
- [servant-miso-router](https://github.com/haskell-miso/servant-miso-router): A servant router for miso.
- [servant-miso-client](https://github.com/haskell-miso/servant-miso-client): A servant-client interpretation for miso.
- [try-miso](https://github.com/haskell-miso/try-miso): Try miso in the browser. Live demo: https://try.haskell-miso.org/

## Native

- [miso-lynx](https://github.com/haskell-miso/miso-lynx): miso on Lynx: the native mobile backend, tooling and docs.
- [miso-lynx-gallery](https://github.com/haskell-miso/miso-lynx-gallery): A gallery of native components.
- [misogram](https://github.com/haskell-miso/misogram): An Instagram clone in miso and LynxJS.


---

# A tour of the new haskell-miso.org

> The site is rebuilt in miso itself: 41 pages of docs with live examples, a native section, 55 examples, full-text search and docs your AI tools can read.

Source: https://haskell-miso.org/blog/a-tour-of-the-new-site/

Published 2026-10-22

haskell-miso.org has been rebuilt from the ground up, in miso. Every page is a miso `Component`, prerendered to static HTML and then hydrated by the same code compiled to WebAssembly. Here is a tour of what is new.

## Documentation with live examples

The [documentation](https://haskell-miso.org/docs/) now runs to 41 pages, from [your first Component](https://haskell-miso.org/docs/your-first-component/) through effects, subscriptions, routing and prerendering, all the way down to the [internals](https://haskell-miso.org/docs/internals/). Twelve of them include a **live example**: a running component next to its source. The source shown is the code that is running, and CI checks that the two never drift apart.

## Thinking in miso

[Thinking in miso](https://haskell-miso.org/docs/thinking/overview/) is a guided walk-through that takes an application from a mockup to a working program: design the model, split the view, define the actions, then connect the pieces and ship. If you are coming from React, [miso vs. React](https://haskell-miso.org/docs/thinking/miso-vs-react/) maps hooks onto their miso counterparts, and points out the names that look alike but are not.

## Native apps

miso drives the [Lynx](https://lynxjs.org) runtime to build native iOS and Android apps from the same components you write for the web. The [native section](https://haskell-miso.org/docs/native/overview/) explains how it works: the [dual-thread architecture](https://haskell-miso.org/docs/native/dual-thread/), static mounting, main-thread events and state, and a [minimal native component](https://haskell-miso.org/docs/native/minimal-component/) to start from.

## Examples

The [examples page](https://haskell-miso.org/examples/) collects 55 applications and libraries from the [haskell-miso organisation](https://github.com/haskell-miso): games, browser API demos, integrations with JavaScript libraries, and tooling. Most of them have a live demo one click away.

## Finding things

Press `⌘K` (or `Ctrl+K`) on any page to search. Search covers the full text of the documentation, so a function name such as `startSub` finds every page that uses it, not just the page named after it.

## Docs your tools can read

Every documentation page also has a Markdown copy, linked from the page and listed in [llms.txt](https://haskell-miso.org/llms.txt). The whole documentation is in a single file, [llms-full.txt](https://haskell-miso.org/llms-full.txt), ready to hand to an AI assistant. All of it is generated from the same source as the pages, so it is never out of date.

## Get involved

The site's source is at [haskell-miso/haskell-miso.org](https://github.com/haskell-miso/haskell-miso.org), and issues and pull requests are welcome, whether it is a typo or a new docs page. Questions and show-and-tell go to [Discord](https://discord.gg/QVDtfYNSxq) or [Matrix](https://matrix.to/#/#haskell-miso:matrix.org).


---

# New blog

> Welcome to the new home of haskell-miso.org. More blog posts coming soon.

Source: https://haskell-miso.org/blog/new-blog/

Published 2026-08-18

Welcome to the new home of [haskell-miso.org](https://haskell-miso.org). More blog posts coming soon.

Please see the [native section](https://haskell-miso.org/docs/native/overview/) and the [miso-lynx-gallery](https://github.com/haskell-miso/miso-lynx-gallery) for the latest on mobile application development.