Cinder

Tables, lists and grids of Ash resources in Phoenix LiveView, with filtering, sorting, search and pagination.

[!NOTE] Cinder 1.0 is being built on main, so this branch may not match the released version. For the released docs, see cinder.hexdocs.pm, and for 0.18 fixes, the 0.18-stable branch.

<Cinder.collection resource={MyApp.User} actor={@current_user}>
  <:col :let={user} field="name" filter sort>{user.name}</:col>
  <:col :let={user} field="email" filter>{user.email}</:col>
  <:col :let={user} field="department.name" filter sort>{user.department.name}</:col>
  <:col :let={user} field="settings__country" filter>{user.settings.country}</:col>
</Cinder.collection>

Cinder reads your Ash resource to pick each filter's type (enums become selects, dates become date pickers, and so on), and loads what each column shows, including relationships, calculations and aggregates.

Features

• Table, list and grid layouts, which share filtering, sorting and pagination
• Filters for text, numbers, dates, booleans, enums and arrays, plus your own
• Search across any columns you choose
• Sorting on one or more columns, with configurable cycles and tiebreakers
• Pagination, offset or keyset, with the total counted alongside, in the background, or not at all
• Relationship and embedded fields: department.name, settings__country
• URL sync, so filters, sorting and pages can be bookmarked and shared
• Selection and bulk actions
• Refreshing and updating rows after changes, without reloading the page
• Themes: 8 built in, or your own
• Translations for nine languages, including English
• Telemetry for every load

Installation

With Igniter:

mix igniter.install cinder

This adds the dependency, sets up Tailwind and the daisy_ui theme, and registers Cinder's LiveView hook. To install by hand, see Getting Started.

Quick Start

<Cinder.collection resource={MyApp.User} actor={@current_user}>
  <:col :let={user} field="name" filter sort>{user.name}</:col>
  <:col :let={user} field="email" filter>{user.email}</:col>
  <:col :let={user} field="role" filter>{user.role}</:col>
</Cinder.collection>

For a list or grid, describe each item with an <:item> slot. The <:col> slots then only configure filtering and sorting:

<Cinder.collection resource={MyApp.Product} actor={@current_user} layout={:grid} grid_columns={3}>
  <:col field="name" filter sort />
  <:item :let={product}>
    <div class="p-4 border rounded">{product.name}</div>
  </:item>
</Cinder.collection>

Documentation

• Getting Started: installation, layouts, columns and themes
• Filters: filter types, search, and laying out the filters yourself
• Sorting: sort cycles, modes, defaults and tiebreakers
• Advanced Features: URL sync, relationships, refreshing, pagination, selection and bulk actions, telemetry
• Theming: built-in themes and writing your own
• Localization: translations and your own Gettext backend
• Upgrading: what changed in each version, and how to upgrade
• API reference

Requirements

• Phoenix LiveView 1.1+
• Ash Framework 3.24.5+
• Elixir 1.17+

Contributing

dev/ holds a Phoenix app for trying out Cinder's features by hand: each layout, every filter type, pagination, selection and bulk actions, and the custom slots, with a switcher for the built-in themes. It uses Cinder from this repo, so changes to lib/ reload in the browser without a restart.

cd dev
mix setup
iex -S mix phx.server

Then visit localhost:4000. mix check, run from the repo root, also runs the dev app's tests.

License

MIT License - see LICENSE file for details.