Filters

This guide covers every filter type, filters without a column, search, and laying out the filters yourself. For a first collection, see Getting Started.

Table of Contents

• Choosing a Filter Type
• Filter Types
• What Can Be Filtered
• Filters Without a Column
• Collapsible Filters
• Search
• Custom Filter Functions
• Laying Out the Filters Yourself

See also: Sorting | Custom Filters

Choosing a Filter Type

filter on its own picks the filter type from the field's Ash type:

To choose the type, give it instead of true, as an atom or a string:

<:col :let={user} field="status" filter={:radio_group}>{user.status}</:col>

To give options as well, pass a keyword list with the type under type:

<:col :let={user} field="status" filter={[type: :select, options: [{"Active", "active"}, {"Suspended", "suspended"}]]}>
  {user.status}
</:col>

Every filter takes a label option, which changes the filter's label without changing the column's heading: filter={[type: :text, label: "Title contains"]}.

Filters that offer a list of options (select, multi-select, multi-checkboxes, radio group and autocomplete) take them as {label, value} tuples. On an enum field, or an array of one, they list the enum's values when you don't give options.

Filter Types

Text

Matches values containing the text, ignoring case:

<:col :let={article} field="title" filter>{article.title}</:col>

<:col :let={article} field="content" filter={[type: :text, placeholder: "Search content..."]}>
  {article.content}
</:col>

Select

A dropdown for choosing one value:

<:col :let={user} field="role" filter>{user.role}</:col>

<:col :let={user} field="department" filter={[type: :select, options: @departments, prompt: "All departments"]}>
  {user.department}
</:col>

Multi-Select and Multi-Checkboxes

Both choose any number of values: :multi_select as a dropdown of checkboxes, and :multi_checkboxes as a list of checkboxes.

<:col :let={product} field="tags" filter={[type: :multi_select, options: @tags]}>
  {Enum.join(product.tags, ", ")}
</:col>

<:col :let={user} field="role" filter={[type: :multi_checkboxes, options: [{"Admin", "admin"}, {"Editor", "editor"}]]}>
  {user.role}
</:col>

On a single-value field, a record matches if its value is one of those chosen. On an array field (including a list aggregate, or an array through a relationship like albums.tags), a record matches if its array holds any of them, or all of them with match_mode: :all:

<:col field="tags" filter={[type: :multi_select, options: @tags, match_mode: :all]} />

Boolean

Radio buttons for true and false. With neither chosen, records aren't filtered by it:

<:col :let={user} field="verified" filter={[type: :boolean, labels: %{true: "Verified", false: "Unverified"}]}>
  {user.verified}
</:col>

Radio Group

Radio buttons for choosing one value from a short list:

<:col :let={order} field="status" filter={[type: :radio_group, options: [{"Pending", "pending"}, {"Shipped", "shipped"}, {"Delivered", "delivered"}]]}>
  {order.status}
</:col>

Checkbox

A single checkbox, for "only show these":

<!-- On a boolean field, checking it shows the true ones -->
<:col :let={article} field="published" filter={[type: :checkbox, label: "Published only"]}>
  {article.published}
</:col>

<!-- On any other field, checking it shows those with the value -->
<:col :let={article} field="priority" filter={[type: :checkbox, value: "high", label: "High priority only"]}>
  {article.priority}
</:col>

Date

A single date picker that matches one day: the whole day, on a datetime field. Date and datetime fields get a date range by default, so choose this one:

<:col :let={order} field="delivered_on" filter={:date}>{order.delivered_on}</:col>

Date Range

From and to date pickers. Either can be left empty for an open-ended range:

<:col :let={order} field="shipped_at" filter={[type: :date_range, include_time: true]}>
  {order.shipped_at}
</:col>

Number Range

Minimum and maximum inputs. Either can be left empty:

<:col :let={product} field="quantity" filter={[type: :number_range, min: 0, max: 10000, step: 10]}>
  {product.quantity}
</:col>

Autocomplete

A text box that lists matching options as you type, for when there are too many for a dropdown:

<:col :let={order} field="customer_id" filter={[type: :autocomplete, options: @customers, max_results: 15]}>
  {order.customer.name}
</:col>

What Can Be Filtered

A column can filter by an attribute, a field through relationships (artist.name), a field of an embedded resource (profile__country), an aggregate, or a calculation the data layer can run (an expression calculation). See Advanced Features for more on relationship and embedded fields.

A column with filter on a field that can't be filtered by gets no filter, and logs a warning. That's a field that doesn't exist, a calculation run in Elixir rather than the data layer, or a calculation that needs arguments. In 1.0 this raises.

Values that don't fit a filter are ignored rather than used, like a date that isn't a date in a hand-edited URL, or a choice that isn't one of the filter's options. Multi-select filters with no options keep at most 100 values.

Filters Without a Column

A <:filter> slot adds a filter for a field that has no column, like a date you filter by but don't show:

<Cinder.collection resource={MyApp.Order} actor={@current_user}>
  <:col :let={order} field="order_number">{order.order_number}</:col>
  <:col :let={order} field="total">{order.total}</:col>

  <:filter field="inserted_at" type={:date_range} label="Order date" />
  <:filter field="status" type={:select} options={[{"Pending", "pending"}, {"Shipped", "shipped"}]} />
  <:filter field="customer_name" placeholder="Customer name..." />
</Cinder.collection>

A field can't have both a <:filter> slot and a column with filter.

It also takes any of the filter types' options as attributes: options, prompt, operator, case_sensitive, placeholder, labels, value, match_mode, include_time, min, max, step and max_results.

Collapsible Filters

With many filters, the filter inputs can start hidden. The header, with the active filter count and "Clear all", stays visible, with a button that shows and hides the inputs without a trip to the server:

<!-- Starts hidden -->
<Cinder.collection resource={MyApp.User} actor={@current_user} show_filters={:toggle}>
  ...
</Cinder.collection>

<!-- Starts shown -->
<Cinder.collection resource={MyApp.User} actor={@current_user} show_filters={:toggle_open}>
  ...
</Cinder.collection>

String values ("toggle") work too. Set the default for every collection in your config:

config :cinder, show_filters: :toggle

Search

The search box filters across every column with search at once, showing records where any of them contains the text, ignoring case:

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

The search box appears when a column has search. Change its label and placeholder, or turn it off, with the collection's search attribute:

<Cinder.collection resource={MyApp.Album} search={[label: "Find albums", placeholder: "Title or artist..."]}>
  <:col :let={album} field="title" search>{album.title}</:col>
  <:col :let={album} field="artist.name" search>{album.artist.name}</:col>
</Cinder.collection>

<Cinder.collection resource={MyApp.Album} search={false}>
  ...
</Cinder.collection>

A column with search on a field that can't be searched logs a warning, like filter does.

Custom Search

To search your own way, pass a function as fn. It receives the query, the columns with search, and the text, and returns the query with your filter. It's only called when at least one column has search:

<Cinder.collection resource={MyApp.Album} search={[fn: &MyApp.AlbumSearch.search/3]}>
  <:col :let={album} field="title" search>{album.title}</:col>
</Cinder.collection>

defmodule MyApp.AlbumSearch do
  require Ash.Query

  # An exact catalogue number, or part of the title
  def search(query, _columns, text) do
    Ash.Query.filter(query, catalogue_number == ^text or contains(title, ^text))
  end
end

Custom Filter Functions

To filter in a way the built-in filters can't, give a filter a fn. It receives the query and the filter's value, and returns the query with your filter:

<:col :let={invoice} field="status" filter={[type: :select, options: @statuses, fn: &filter_status/2]}>
  {invoice.status}
</:col>

require Ash.Query

# "Overdue" isn't a status: it's a pending invoice past its due date
def filter_status(query, %{value: "overdue"}) do
  today = Date.utc_today()
  Ash.Query.filter(query, status == "pending" and due_date < ^today)
end

def filter_status(query, %{value: status}) do
  Ash.Query.filter(query, status == ^status)
end

The value is a map with the filter's :type, :value and :operator, plus :case_sensitive for text filters and :match_mode for multi-value ones.

Laying Out the Filters Yourself

The :controls slot replaces how the filters and search box are laid out, while Cinder still handles their state, the URL, and the query:

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

  <:controls :let={controls}>
    <div class="flex items-center gap-4 mb-4">
      <Cinder.Controls.render_search search={controls.search} theme={controls.theme} target={controls.target} />
      <button type="button" phx-click="export">Export</button>
    </div>
    <div class="grid grid-cols-2 gap-4">
      <Cinder.Controls.render_filter
        :for={{_field, filter} <- controls.filters}
        filter={filter}
        theme={controls.theme}
        target={controls.target}
        raw_filter_params={controls.raw_filter_params}
      />
    </div>
  </:controls>
</Cinder.collection>

Cinder wraps the slot in its filter form, so inputs named like Cinder's own (filters[status] for a field called status) work without anything else. That means you can mix the helpers with your own inputs:

<:controls :let={controls}>
  <Cinder.Controls.render_header {controls} />
  <div class="flex gap-4">
    <Cinder.Controls.render_filter filter={controls.filters[:name]} theme={controls.theme} target={controls.target} />
    <.my_select
      name="filters[status]"
      value={controls.filters[:status].value}
      options={[{"Active", "active"}, {"Inactive", "inactive"}]}
    />
  </div>
</:controls>

Helpers

• Cinder.Controls.render_filter/1: one filter, with its label, input and clear button. Pass raw_filter_params for autocomplete filters, so they keep what's been typed.
• Cinder.Controls.render_search/1: the search box.
• Cinder.Controls.render_header/1: the header, with the label, active filter count, "Clear all" and the show/hide toggle.

What the Slot Receives