# `Ascii.Phoenix.PlayerComponent`
[🔗](https://github.com/houllette/ascii_art/blob/main/lib/ascii/phoenix/player_component.ex#L2)

A LiveComponent that plays a piece inside your LiveView and takes new
options as they change: for live data, a reading for a gauge, the latest
samples for a sparkline.

    <Ascii.Phoenix.live_player id="load" piece="gauge" options={%{label: "load", value: @load}} />

or, the same, `<.live_component module={Ascii.Phoenix.PlayerComponent}
id="load" ... />`. Each time your LiveView renders it with other
`options`, the piece takes them up while it plays
(`Ascii.put_options/2`): the gauge's needle swings from the last
reading to the new one, bars ease to new values, a sparkline scrolls on.
Another `piece`, `fps`, `paper`, `mono`, `ink`, `gradient`, `parts` or
`render` starts it afresh.

It plays as `Ascii.Phoenix.PlayerLive` does, with the same hook and
the same economy: a loop is sent to the browser once, anything else as
the cells that change, nothing while out of sight (see that module). The
difference is where it runs: in your LiveView's process, whose state the
options come from, rather than in a LiveView of its own. That suits
widgets, which draw in well under a millisecond; a 200×100 scene costs
milliseconds a frame, and is better in `Ascii.Phoenix.player/1`.

## Attributes

`id` (required, unique on the page), `piece` (a slug or a module),
`options`, `fps`, `paper`, `mono`, `ink`, `gradient`, `parts`, `render`
(`:client`, the default, or `:server`), `label`, `interactive` and
`notify`, as for `Ascii.Phoenix.player/1`.

## Keys and clicks

With `interactive`, the piece takes keys and clicks
(`Ascii.handle_event/2`): a file tree's cursor moves, a form's box
ticks. With `notify`, your LiveView is sent each of them as well, as
`{:ascii, id, %{event: event, part: part, text: text, options:
options}}`: the event, the part clicked and its text (see
`Ascii.part_at/4`), and the options the piece now has, from which to
read what was chosen.

    def handle_info({:ascii, "files", %{event: {:key, "enter"}, options: options}}, socket),
      do: {:noreply, open_file(socket, options.cursor)}

The options you give are merged over what the piece's events have
changed, so leave out those it keeps (a tree's `cursor` and `open`, a
form's `fields`) unless you mean to set them, and never give back what
it told you: it has that already, and keys typed in the meantime would
be undone.

Only available when `phoenix_live_view` is a dependency.

---

*Consult [api-reference.md](api-reference.md) for complete listing*