# 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))
```
