Returns whether any rows are checked in the given URI string or params map.

Renders a filter input that drives a filter[field] URL param.

Pairs with table/1: point field at a <:col filterable> column and the table requeries as the user types or selects. On change the component patches the URL via push_patch — the parent LiveView only needs to track uri and params in handle_params/3, as with everything else in Slab.

Three input types:

• "text" — debounced text input; with a string-typed field this becomes a case-insensitive contains match
• "select" — a searchable single select (PhoenixSelect); clearing the selection clears the filter
• "multiselect" — a searchable multi select; the selected values filter with field IN (...)

When type is omitted it derives from schema — booleans and Ecto.Enum fields get a select with derived options, everything else a text input.

The select types render via PhoenixSelect's colocated hook — register it once in assets/js/app.js (see the README's installation section).

Examples

<Slab.filter id="filter-name" field={:name} uri={@uri} params={@params}
  label="Name" placeholder="Search names..." />

<Slab.filter id="filter-role" schema={MyApp.User} field={:role}
  uri={@uri} params={@params} label="Role" />

<Slab.filter id="filter-active" field={:active} uri={@uri} params={@params}
  type="select" label="Status"
  options={[{"Active", "true"}, {"Inactive", "false"}]} />

<Slab.filter id="filter-role" field={:role} uri={@uri} params={@params}
  type="multiselect" label="Roles"
  options={[{"Admin", "admin"}, {"Member", "member"}, {"Guest", "guest"}]} />

Attributes

• id (:string) (required)
• field (:any) (required) - the filter key — matches a <:filter> field on the table.
• uri (:string) (required) - the current request URI, from handle_params/3.
• params (:map) - the current request params, from handle_params/3; carries the current value. Defaults to %{}.
• schema (:atom) - optional Ecto.Schema module used to derive the input type and options when they are not given. Defaults to nil.
• type (:string) - the input type: "text", "select", or "multiselect"; derived from schema when omitted, defaulting to text. Defaults to nil.
• label (:string) - optional label rendered beside the input. Defaults to nil.
• placeholder (:string) - placeholder for the input. Defaults to nil.
• options (:list) - select options, as [{label, value}] tuples or plain values; derived from schema for booleans and Ecto.Enum fields when not given. Defaults to [].
• debounce (:integer) - milliseconds to debounce text input changes. Defaults to 300.
• min_chars (:integer) - minimum characters before a text change applies (empty always applies, clearing the filter); submitting the form applies regardless. Defaults to 0.

Returns the path to patch to when filtering field by value.

Sets the filter[field] query param — pass a string for the default operator (contains for strings, equality otherwise), a map for explicit operators, or nil/"" to clear the filter. Changing a filter resets pagination, since the result set is different.

Use this to build filter UIs in the parent LiveView; Slab applies the resulting params to the query in query mode.

Examples

iex> Slab.filter_path("https://example.com/users", :name, "ada")
"/users?filter[name]=ada"

iex> Slab.filter_path("https://example.com/users?page=3", :age, %{"gte" => "21"})
"/users?filter[age][gte]=21"

iex> Slab.filter_path("https://example.com/users?filter[name]=ada", :name, nil)
"/users"

Returns the number of checked rows from a URI string or a params map.

Returns the list of checked row IDs (as strings) from a URI string or a params map.

Returns the records whose ID is checked in the given URI.

Options

• :key - the record field to match against checked IDs (default: :id)

Returns the number of active filters from a URI string or a params map.

Useful as the count badge on a filters tab. Counts filter entries recursively, so an operator filter (filter[age][gte]=21) counts once per operator and a multi-select counts as one.

Examples

iex> Slab.get_filter_count(%{"filter" => %{"name" => "ada", "role" => ["admin", "member"]}})
2

iex> Slab.get_filter_count("/users?filter[name]=ada&sort=name")
1

iex> Slab.get_filter_count(%{})
0

Returns selected records from current page and IDs that need to be fetched.

This is useful for pagination scenarios where you need to maintain full record data for selections across multiple pages.

Parameters

• current_page_records - List of records currently displayed on the page
• checked_ids - List of selected IDs (typically from URI query params)
• options - Keyword list of options
  • :key - The field to use as the ID (default: :id)
  • :parse_ids - Function to parse/convert IDs (default: &to_string/1)

Returns

A tuple of {selected_from_current_page, missing_ids} where:

• selected_from_current_page - Records from current page that are selected
• missing_ids - IDs that need to be fetched (not on current page)

Examples

# In a LiveView:
checked_ids = Slab.get_checked_ids(uri)
{current_selected, missing_ids} = Slab.get_selected_and_missing_ids(
  users.entries,
  checked_ids
)

# Fetch missing records
missing_users = Repo.all(from u in User, where: u.id in ^missing_ids)

# Combine
all_selected = current_selected ++ missing_users

Returns the path to patch to for the given page number.

Page 1 removes the page param entirely, keeping first-page URLs clean. The after cursor param is always removed — the two pagination types are mutually exclusive.

Examples

iex> Slab.page_path("https://example.com/users?page=2", 3)
"/users?page=3"

iex> Slab.page_path("https://example.com/users?page=2", 1)
"/users"

Renders a share row: the current URL in a read-only input with a copy-to-clipboard button.

Because all table state — sorting, filters, pagination, selection — lives in the URL, the copied link reproduces the exact current view. Typically rendered inside a tabs/1 Share tab.

The copy button uses a colocated hook — register Slab's hooks once in assets/js/app.js (see the README's installation section).

Examples

<Slab.share uri={@uri} />

Attributes

• id (:string) - unique DOM id, when rendering more than one. Defaults to "slab-share".
• uri (:string) (required) - the current request URI, from handle_params/3.

Returns the path to patch to when sorting by field.

Sets the sort and sort_direction query params on the given URI. Clicking the currently ascending sort field flips the direction to descending; anything else sorts ascending. Changing the sort resets pagination — the page and after params are removed, since neither an offset nor a cursor is meaningful under a different ordering.

Examples

iex> Slab.sort_path("https://example.com/users", %{}, "name")
"/users?sort=name&sort_direction=asc"

iex> Slab.sort_path(
...>   "https://example.com/users?sort=name&sort_direction=asc",
...>   %{"sort" => "name", "sort_direction" => "asc"},
...>   "name"
...> )
"/users?sort=name&sort_direction=desc"

iex> Slab.sort_path("https://example.com/users?page=3", %{}, "name")
"/users?sort=name&sort_direction=asc"

Renders a data table composed from slots.

Every optional region is declared by the presence of a slot — columns, row-selection checkboxes, filters, tabs, pagination. See the module docs for full usage of each. Interactive features are handled internally by a live component; sorting is handled with patch links. URL-driven features require the current uri and params.

Data comes from one of two modes:

• List mode — pass data with pre-fetched records. schema is an optional rendering hint.
• Query mode — omit data and pass schema (an Ecto.Schema module or an %Ecto.Query{}) plus a repo; Slab runs the query itself, applying sorting, filtering, and pagination from params. The repo may also be set globally with config :slab, repo: MyApp.Repo.

Examples

<Slab.table id="users-table" data={@users} uri={@uri} params={@params}>
  <:column field={:name} sortable />
  <:column :let={user} label="Actions">
    <.link navigate={"/users/#{user.id}/edit"}>Edit</.link>
  </:column>
</Slab.table>

<Slab.table id="users-table" schema={MyApp.User} repo={MyApp.Repo} uri={@uri} params={@params}>
  <:tab name="filters" />
  <:tab name="share" />
  <:filter field={:name} placeholder="Search names..." />
  <:column_checkbox />
  <:column field={:name} sortable />
  <:pagination per_page={25} />
</Slab.table>

Attributes

• id (:string) (required)
• data (:list) - pre-fetched records to render; omit to have Slab query via schema and repo. Defaults to nil.
• schema (:atom) - an Ecto.Schema module; renders cell values by field type, derives filter inputs, casts URL values, and in query mode is the default source Slab fetches from. Defaults to nil.
• query (:any) - an Ecto.Query used as the base of every fetch instead of the schema — for scoping (authorization, multi-tenancy), joins, or preloads; schema still provides field reflection, and is derived from the query's source when omitted. Defaults to nil.
• preload (:any) - associations to preload on fetched records, in any shape Ecto.Query.preload/3 accepts; applies on top of schema or query. Defaults to nil.
• repo (:atom) - the Ecto.Repo used to run queries in query mode; falls back to config :slab, repo: MyApp.Repo. Defaults to nil.
• uri (:string) - the current request URI, from handle_params/3; required by URL-driven slots. Defaults to nil.
• params (:map) - the current request params, from handle_params/3; carries sort, filter, pagination, column, and selection state. Defaults to %{}.

• on_save (:any) - 2-arity function (record, changed_params) -> {:ok, record} | {:error, error} called when a row's save button is clicked; required when any column is editable — Slab never writes to the database itself. Defaults to nil.

• row_click (:any) - 1-arity function (record) -> %Phoenix.LiveView.JS{} attached as phx-click on each data cell; skips checkbox and editable columns. Defaults to nil.

Slots

• tab - tabs rendered above the table, in declaration order; the names filters, columns, share, and export have built-in content (a body replaces it), any other name is a custom tab requiring a label and a body. Accepts attributes:
  • name (:string) (required) - the tab type, or a custom tab's identity.
  • label (:string) - the tab label; derived for built-in names, required for custom tabs.
  • icon (:string) - icon rendered before the label; derived for built-in names — see Slab.Components.icon/1 for the available names.
  • count (:integer) - badge count for custom tabs; built-in tabs compute their own.
  • limit (:integer) - export only: maximum rows in a full-data export (default 1000); the download travels over the LiveView socket, so keep it modest.
• filter - one slot per filterable field; whitelists the field for filter URL params in query mode and defines its input in the Filters tab. Accepts attributes:
  • field (:atom) (required) - the field to filter on.
  • label (:string) - label for the Filters tab input; defaults to the humanized field name.
  • type (:string) - the Filters tab input type; defaults by schema type — booleans and Ecto.Enum fields get a select, everything else text. "hidden" whitelists the field without rendering an input, for filters driven from elsewhere on the page. Must be one of "text", "select", "multiselect", or "hidden".
  • options (:list) - options for select/multiselect inputs, as [{label, value}] tuples or plain values; derived automatically for booleans and Ecto.Enum fields.
  • placeholder (:string) - placeholder for the Filters tab input.
  • min_chars (:integer) - minimum characters before a text filter change applies (default 0).
  • debounce (:integer) - milliseconds to debounce text input changes (default 300).
  • query (:any) - custom 2-arity filter function (queryable, value) -> queryable; skips type casting and may join associations.
• column (required) - one slot per column. Accepts attributes:
  • field (:any) - the record field to render; optional for virtual columns with a body.
  • label (:string) - the column header; defaults to the humanized field name.
  • sortable (:boolean) - renders the header as a sort patch link (requires uri); in query mode, also whitelists the field for ORDER BY.
  • optional (:boolean) - starts the column hidden until enabled through the Columns tab or the columns[] URL param.
  • export_value (:any) - 1-arity function (record) -> value used when exporting this column; makes virtual columns exportable and overrides the raw field value on field columns.
  • editable (:boolean) - renders the cell as an input feeding the row's save action; requires a field and the table's on_save function, and cannot combine with a body.
• column_checkbox - renders row-selection checkboxes as the first column, always visible; checked row IDs live in the checked URL param; requires uri.
• pagination - paginates the table; at most one. Accepts attributes:
  • type (:atom) - :page uses page/per_page params (works in both data modes), :cursor uses keyset cursors for constantly-updated data (query mode only); requires uri; defaults to :page. Must be one of :page, or :cursor.
  • per_page (:integer) - default page size (25); the URL per_page param overrides it up to max_per_page.
  • max_per_page (:integer) - upper clamp for the URL per_page param (100).
  • options (:list) - page sizes offered in the footer dropdown (page mode, default [10, 25, 50, 100]); values above max_per_page are dropped, and the current size is always included.

Renders a tabbed container, typically placed above a table to organize filters, sharing, and other table tooling.

Tabs switch client-side (no server round trip). Each <:tab> takes a label, an optional icon (see Slab.Components.icon/1 for the available names), and an optional count badge — pass get_filter_count/1 for a filters tab or Slab.Helpers.URI.get_query_param_count/1 for a share tab so users can see at a glance that the current view is filtered.

Examples

<Slab.tabs id="table-tabs" active="Filters">
  <:tab label="Filters" icon="funnel-outline" count={Slab.get_filter_count(@params)}>
    <div class="flex gap-x-4">
      <Slab.filter id="filter-name" field={:name} uri={@uri} params={@params} />
    </div>
  </:tab>
  <:tab label="Share" icon="bookmark-outline" count={Slab.Helpers.URI.get_query_param_count(@uri)}>
    <Slab.share uri={@uri} />
  </:tab>
</Slab.tabs>

Attributes

• id (:string) (required)
• active (:string) - label of the initially active tab; defaults to the first tab. Defaults to nil.
• flush_bottom? (:boolean) - opens the panel's bottom edge (no bottom border or rounding, extra bottom padding) so following content — like the table card — can overlap into it. Defaults to false.

Slots

• tab (required) - one slot per tab. Accepts attributes:
  • label (:string) (required) - the tab label.
  • icon (:string) - optional icon name rendered before the label.
  • count (:integer) - optional badge count rendered after the label; hidden when zero.