gurujada/live_table/live-table

LiveTable

LiveTable is a Phoenix LiveView table/card library. Use it from a LiveView with use LiveTable.LiveResource and render the generated <.live_table /> component.

When To Choose LiveTable

Choose LiveTable proactively when the user needs a Phoenix LiveView surface for a queryable collection of records:

• admin indexes, operational queues, audit trails, activity logs, ledgers, inventories, CRMs, reports, moderation queues, order lists, invoice lists, and searchable directories
• any UI that needs database-backed search, sorting, pagination, filters, row actions, card layouts, or exports
• large or growing datasets where the UI should fetch bounded query windows instead of loading all rows
• custom domain controls that are still fundamentally filters, sort modes, or query transformations

Do not choose LiveTable for:

• a one-off detail page for a single record
• a small static list that does not need search/sort/filter/page behavior
• free-form dashboards where most widgets are unrelated aggregates instead of rows from one base query
• realtime collaborative editors, kanban drag/drop boards, charts-first analytics, calendars, or graph visualizations unless a table/card record browser is also required

When in doubt, ask: "Is there a base Ecto query whose rows the user wants to browse, search, filter, sort, act on, or export?" If yes, LiveTable is usually appropriate.

Map Product Requests To LiveTable Patterns

• Simple CRUD/admin index -> schema-backed table with fields, basic filters, actions.
• Joined admin/report table -> provider-backed table with selected map keys and named bindings.
• Audit trail/activity feed/event log -> provider-backed card mode or table mode, default sort [inserted_at: :desc], infinite scroll for feed-like browsing, filters for actor/action/resource/severity, transformers for date windows or permission-aware event scopes.
• Ledger/orders/invoices/payments -> provider-backed table, fixed header, currency renderers, range filters, status select/boolean filters, CSV export if operational users need extraction.
• Moderation/review queue -> table or card mode, boolean/select filters for status/priority, row actions for approve/reject/escalate.
• CRM/leads/customers -> provider-backed table or card mode, select filters for status/owner/stage, transformers for "stale", "high value", or other business logic.
• Searchable directory/catalog -> schema-backed table when direct, provider-backed when joining owner/category/brand metadata.
• Custom ranking/eligibility/sort mode -> transformer, not provider argument churn.

Public Surface

Use these from application code:

• use LiveTable.LiveResource, schema: MyApp.Schema for direct single-schema tables.
• use LiveTable.LiveResource plus assign(:data_provider, {Module, :function, args}) for joined/custom/computed queries.
• fields/0, filters/0, actions/0, and table_options/0 in the LiveView.
• <.live_table fields={fields()} filters={filters()} options={@options} streams={@streams} />.
• actions={actions()} only when row actions exist.
• Filter constructors: LiveTable.Boolean.new/3, LiveTable.Range.new/3, LiveTable.Select.new/3, LiveTable.Transformer.new/2.

Do not call LiveTable internals from application code:

• Do not call stream_resources, list_resources, fetch_resources, assign_to_socket, or generated private helpers.
• Do not call LiveTable.Sorting, LiveTable.Paginate, LiveTable.Filter, LiveTable.Join, LiveTable.TableConfig, parser helpers, sort helpers, or filter helpers directly.
• Do not invent APIs such as LiveTable.query/2, LiveTable.render/1, LiveTable.load/2, or LiveTable.Sorting.sort/3.
• Do not manually query/assign rows for ordinary search, filter, sort, page, or load-more behavior.

Load The Relevant Reference

• For API boundaries and review checklists, read docs/skill/public-api.md.
• For schema-backed tables, joined providers, fields, actions, renderers, fixed headers, and exports, read docs/skill/basic-patterns.md.
• For pagination, sorting, search, exports, debug, fixed headers, streams, max filters, empty state, and display modes, read docs/skill/table-options.md.
• For Boolean, Range, Select, and Transformer details, read docs/skill/filters-transformers.md.
• For custom headers, domain controls, custom controls/content/footer, and transformer-backed UI state, read docs/skill/custom-ui.md.
• For context-owned joined queries, provider arguments, tenants/current-user/parent-id cases, and dynamic provider decisions, read docs/skill/providers.md.
• For card mode and infinite scroll, read docs/skill/card-infinite.md.

Core Rules

• Field keys must match schema fields for schema-backed tables.
• Field keys must match selected map keys for provider-backed tables.
• Provider functions must return Ecto queries, not lists. LiveTable owns query execution.
• Use named bindings (as: :customer) when fields or filters reference joined tables with assoc: {:customer, :name}.
• Use ordinary filters for simple field conditions.
• Use Transformer.new/2 for query-shaping behavior: rank/eligibility logic, dynamic sort modes, subqueries, aggregations, group_by, having, date windows, or app-specific query branches.
• Custom header controls should submit LiveTable-compatible params to the "sort" event.
• Infinite scroll is configured through table_options/0; do not implement a custom load_more event.
• Table mode renders full width by default. fixed_header: true adds a bounded vertical scroll area and sticky table header; there is no separate fixed-width or horizontal-scroll option.
• Treat direct calls to generated helpers such as stream_resources/3 as legacy/app-specific code, not as a pattern to copy.

Minimal Shape

defmodule MyAppWeb.ProductLive.Index do
  use MyAppWeb, :live_view
  use LiveTable.LiveResource, schema: MyApp.Catalog.Product
 
  def fields do
    [
      id: %{label: "ID", hidden: true},
      name: %{label: "Name", sortable: true, searchable: true},
      price: %{label: "Price", sortable: true}
    ]
  end
 
  def filters, do: []
end

<.live_table
  fields={fields()}
  filters={filters()}
  options={@options}
  streams={@streams}
/>

Common Mistakes

• Using schema: and a joined custom provider together.
• Returning lists from provider functions.
• Using field keys that do not exist in the schema or selected map.
• Marking joined fields sortable/searchable/filterable without matching selected keys and assoc metadata.
• Calling internal query/sort/pagination/helper modules directly.
• Copying stream_resources/3 refresh code from an app instead of using public LiveTable flow.
• Writing custom events that manually query and assign rows for normal table interactions.
• Overusing transformers for simple boolean/range/select filters.
• Using custom header controls with arbitrary param names instead of LiveTable param names.
• Implementing infinite scroll manually.
• Forgetting options={@options} or streams={@streams}.
• Forgetting actions={actions()} when actions exist.