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

A generic LiveView to create multiple stateless examples for the Surface Catalogue.

Each example must be a function component defined with the module attribute `@example`.

> **NOTE**: If your examples require manipulating state (data) through `handle_event` callbacks,
> use `Surface.Catalogue.LiveExample` instead.

## Options

Besides the buit-in options provided by the LiveView itself, examples can also
pass the following options at the module level:

  * `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.

Other options can be defined at the module level but also overridden at the
function/example level using the `@example` module attribute. They are:

  * `height` - Required (either for the module or function). 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.

When defined at the module level, i.e. passing to `use Surface.Catalogue.Examples, ...`, the
options apply to all examples. Aside from `subject` and `catalogue`, options can be overridden
at the function level using the `@example` module attribute.

## Examples

### Basic usage

```
@example true
def basic_example(assigns) do
  ~F"""
  <Button>OK</Button>
  """
end
```

### Defining a custom title + docs

```
@example "Example with docs"
@doc "A simple example with documentation"
def example_01(assigns) do
  ~F"""
  <Button>OK</Button>
  """
end
```

### Defining other options

```
@example [
  title: "Example and Code split vertically",
  direction: "vertical",
  height: "110px",
  assert: ["Small", "Medium", "Large"]
]
def vertical(assigns) do
  ~F"""
  <Button size="small" color="info">Small</Button>
  <Button size="medium" color="warning">Medium</Button>
  <Button size="large" color="danger">Large</Button>
  """
end
```

Notice that whenever you want to pass other options using a keyword list as in the
example above, in case you need to customize the title, it must to be passed as
a key/value option as well.

---

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