# `Surface.Catalogue.LiveExample`
[🔗](https://github.com/surface-ui/surface/blob/v0.12.3/lib/surface/catalogue/live_example.ex#L1)

A generic LiveView to create a single live example for the Surface Catalogue.

Use `LiveExample` if your example requires manipulating state (data) through
`handle_event` callbacks. For stateless examples, you should use `Surface.Catalogue.Examples`
as it allows defining multiple examples on a single module.

## Options

Besides the buit-in options provided by the LiveView itself, a LiveExample also
provides the following options:

  * `subject` - Required. The target component of the Example.

  * `catalogue` - Optional. A module that implements the `Surface.Catalogue`
    providing additional information to the catalogue tool. Usually required
    if you want to share your components as a library.

  * `height` - Required. The height of the Example.

  * `title` - Optional. The title of the example.

  * `body` - Optional. Sets/overrides the attributes of the the Example's body tag.
    Useful to set a different background or padding.

  * `direction` - Optional. Defines how the example + code boxes should be displayed.
    Available values are "horizontal" or "vertical". Default is "horizontal" (side-by-side).

  * `code_perc` - Optional. When the direction is "horizontal", defines the percentage of
    the total width that the code box should take. Default is `50`. Note: This configuration
    has no effect when direction is "vertical".

  * `assert` - Optional. When using `catalogue_test/1`, generates simple `=~` assertions for
    the given text or list of texts.

## Example

    defmodule MyApp.Catalogue.MyComponentExample do
      use Surface.Catalogue.LiveExample,
        subject: MyApp.MyComponent,
        title: "An example for MyComponent",
        assert: ["Value is 0"]

      data value, :integer, default: 0

      def render(assigns) do
        ~F"""
        <MyApp.MyComponent {=value}/>
        """
      end
    end

---

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