# `Ussd.Pagination`
[🔗](https://github.com/spesohq/ussd/blob/main/lib/ussd/pagination.ex#L1)

Mix into a state alongside a `paginate/1` declaration to page a long listing
without hand-rolling the bookkeeping:

    defmodule MyApp.States.Products do
      use Ussd.State
      use Ussd.Pagination, per_page: 5

      alias Ussd.Decisions.Equal

      paginate next: Equal.new("#"), previous: Equal.new("0")
      transition Ussd.Decisions.Fallback.new(), to: MyApp.States.ProductDetail

      @impl Ussd.Pagination
      def get_items(_context), do: Catalog.list_products()

      @impl Ussd.State
      def render(context) do
        Ussd.Menu.build()
        |> Ussd.Menu.listing(get_items(context), page: current_page(context))
        |> Ussd.Menu.line(if has_next_page?(context), do: "#. More")
      end
    end

Requires `get_items/1`; `per_page` can be given either as the `:per_page` option to
`use Ussd.Pagination` or by implementing `per_page/1` yourself.

# `get_items`

```elixir
@callback get_items(Ussd.Context.t()) :: list()
```

The full, unpaged list of items being paginated.

# `per_page`

```elixir
@callback per_page(Ussd.Context.t()) :: pos_integer()
```

How many items to show per page. Auto-implemented when `use Ussd.Pagination, per_page: n` is given.

---

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