create-item-action

Creating Backpex Item Actions

You are an expert at creating item actions for Backpex. Item actions operate on one or more selected items (rows) in the index view, or on a single item in the show view.

Built-in Item Actions

Default placements:

• show: row only
• edit: row + show page
• delete: row + index toolbar + show page

Creating a Custom Item Action

Use use BackpexWeb, :item_action to set up the behaviour.

Required Callbacks

handle/3 vs link/2

• handle/3: Server-side action. Receives (socket, items, params). Returns {:ok, socket} or {:error, changeset} (only with form fields).
• link/2: Client-side navigation. Receives (assigns, item). Returns a URL string. Enables Ctrl+click.

Defining both raises a CompileError.

Optional Callbacks

Example: Simple Action Without Form

defmodule MyAppWeb.ItemActions.ArchivePost do
  use BackpexWeb, :item_action

  import Ecto.Query

  alias MyApp.Repo

  @impl Backpex.ItemAction
  def icon(assigns, _item) do
    ~H"""
    <Backpex.HTML.CoreComponents.icon name="hero-archive-box" class="h-5 w-5" />
    """
  end

  @impl Backpex.ItemAction
  def label(_assigns, nil), do: "Archive"
  def label(_assigns, item), do: "Archive #{item.title}"

  @impl Backpex.ItemAction
  def confirm(_assigns), do: "Are you sure you want to archive the selected items?"

  @impl Backpex.ItemAction
  def confirm_label(_assigns), do: "Archive"

  @impl Backpex.ItemAction
  def handle(socket, items, _params) do
    ids = Enum.map(items, & &1.id)

    from(p in MyApp.Post, where: p.id in ^ids)
    |> Repo.update_all(set: [archived_at: DateTime.utc_now(:second)])

    {:ok, Phoenix.LiveView.put_flash(socket, :info, "Items archived.")}
  end
end

Example: Action With Form Fields

defmodule MyAppWeb.ItemActions.DuplicatePost do
  use BackpexWeb, :item_action

  import Ecto.Changeset

  alias MyApp.Repo

  @impl Backpex.ItemAction
  def icon(assigns, _item) do
    ~H"""
    <Backpex.HTML.CoreComponents.icon name="hero-document-duplicate" class="h-5 w-5" />
    """
  end

  @impl Backpex.ItemAction
  def label(_assigns, nil), do: "Duplicate"
  def label(_assigns, item), do: "Duplicate #{item.title}"

  @impl Backpex.ItemAction
  def fields do
    [
      title: %{
        module: Backpex.Fields.Text,
        label: "New Title"
      }
    ]
  end

  @impl Backpex.ItemAction
  def confirm(_assigns), do: "Enter a title for the duplicate."

  @impl Backpex.ItemAction
  def confirm_label(_assigns), do: "Duplicate"

  @impl Backpex.ItemAction
  def base_schema(assigns) do
    [item | _] = assigns.selected_items
    item
  end

  @impl Backpex.ItemAction
  def changeset(item, attrs, _metadata) do
    item
    |> cast(attrs, [:title])
    |> validate_required([:title])
  end

  @impl Backpex.ItemAction
  def handle(socket, _items, data) do
    attrs = Map.from_struct(data) |> Map.drop([:id, :inserted_at, :updated_at])

    case Repo.insert(MyApp.Post.changeset(%MyApp.Post{}, attrs, [])) do
      {:ok, _post} -> {:ok, Phoenix.LiveView.put_flash(socket, :info, "Post duplicated.")}
      {:error, _} -> {:ok, Phoenix.LiveView.put_flash(socket, :error, "Failed to duplicate.")}
    end
  end
end

Example: Navigation Action (link)

defmodule MyAppWeb.ItemActions.ViewOnSite do
  use BackpexWeb, :item_action

  @impl Backpex.ItemAction
  def icon(assigns, _item) do
    ~H"""
    <Backpex.HTML.CoreComponents.icon name="hero-arrow-top-right-on-square" class="h-5 w-5" />
    """
  end

  @impl Backpex.ItemAction
  def label(_assigns, _item), do: "View on site"

  @impl Backpex.ItemAction
  def link(_assigns, item), do: "/posts/#{item.slug}"
end

Wiring Into a LiveResource

The item_actions/1 callback receives the default actions (show, edit, delete) and returns a modified keyword list.

@impl Backpex.LiveResource
def item_actions(default_actions) do
  default_actions
  |> Keyword.delete(:delete)
  |> Enum.concat(
    archive: %{module: MyAppWeb.ItemActions.ArchivePost, only: [:row, :index]},
    duplicate: %{module: MyAppWeb.ItemActions.DuplicatePost, only: [:row, :show]}
  )
end

Placement Options

Use only: [...] or except: [...] in the action map to control placement.

Conventions

• File location: lib/my_app_web/item_actions/<snake_case_name>.ex
• Module naming: MyAppWeb.ItemActions.<ActionName>
• Always handle nil item in label/2 (for index-placement buttons)
• Include a type: key in field maps when using schemaless changesets (no base_schema/1 override)
• Authorization is handled via can?/3 in the LiveResource, using the action's keyword key as the action name