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