FilterBuilder component for PhiaUI.

An advanced query-builder UI for constructing multi-condition filter rules at runtime. Each rule is a row containing:

1. A field selector — which column/attribute to filter on
2. An operator selector — how to compare (contains, equals, before, etc.)
3. A value input — the comparison value (text, date, number, or select)
4. A remove button — delete this rule

New rules are added via an "Add filter" button that fires a server event. The entire state is owned by the LiveView — no client-side JS is required.

When to use

Use FilterBuilder for power-user search and reporting interfaces where users need to combine multiple conditions — like the filter panels in Notion, Linear, Airtable, or an admin reporting dashboard.

For simple search + status dropdowns, use FilterBar instead.

Anatomy

Field schema

Each entry in the fields list is a map with:

| :type | "text" | "select" | "date" | "number" | yes | Controls available operators and value input | | :options | [{label, value}] | only for "select" | Options for the value dropdown |

Operator matrix

Complete example — advanced search for a CRM contacts table

defp filter_fields do
  [
    %{name: "name",       label: "Name",       type: "text"},
    %{name: "email",      label: "Email",      type: "text"},
    %{name: "status",     label: "Status",     type: "select",
      options: [{"Active", "active"}, {"Churned", "churned"}, {"Prospect", "prospect"}]},
    %{name: "created_at", label: "Created",    type: "date"},
    %{name: "deal_value", label: "Deal Value", type: "number"}
  ]
end

# In the template:
<.filter_builder
  fields={filter_fields()}
  rules={@filter_rules}
  on_add="add_filter"
  on_remove="remove_filter"
  on_change="update_filter"
/>

LiveView state and handlers

# Default state in mount/3:
def mount(_params, _session, socket) do
  {:ok, assign(socket, filter_rules: [])}
end

# Add a new empty rule (UUID id ensures stable DOM keys):
def handle_event("add_filter", _params, socket) do
  rule = %{id: Ecto.UUID.generate(), field: "name", operator: "contains", value: ""}
  {:noreply, update(socket, :filter_rules, &[&1 | [rule]])}
end

# Remove a specific rule by its id:
def handle_event("remove_filter", %{"id" => id}, socket) do
  {:noreply, update(socket, :filter_rules, &Enum.reject(&1, fn r -> r.id == id end))}
end

# Update a specific rule field when user changes field/operator/value:
def handle_event("update_filter", params, socket) do
  id = params["id"] || params["phx-value-id"]
  rules = Enum.map(socket.assigns.filter_rules, fn rule ->
    if rule.id == id do
      %{rule |
        field:    params["filter"][id]["field"]    || rule.field,
        operator: params["filter"][id]["operator"] || rule.operator,
        value:    params["filter"][id]["value"]    || rule.value
      }
    else
      rule
    end
  end)
  {:noreply, assign(socket, filter_rules: rules)}
end

# Apply rules to a query (example using Ecto):
defp apply_filters(query, rules) do
  Enum.reduce(rules, query, fn
    %{field: "name", operator: "contains", value: v}, q ->
      from(r in q, where: ilike(r.name, ^"%#{v}%"))
    %{field: "status", operator: "equals", value: v}, q ->
      from(r in q, where: r.status == ^v)
    _rule, q -> q
  end)
end