Create Field

Common Field Options (available on all fields)

Creating a Custom Field

Implement Backpex.Field with a @config_schema for field-specific options.

Required Callbacks

@callback render_value(assigns :: map()) :: %Phoenix.LiveView.Rendered{}
@callback render_form(assigns :: map()) :: %Phoenix.LiveView.Rendered{}

render_value/1 is used on both index and show views. render_form/1 is used on new and edit views.

Callbacks With Defaults (overridable)

These are provided by use Backpex.Field and can be overridden as needed:

@callback render_index_form(assigns)  # For index_editable support (only truly optional callback)
@callback display_field(field)         # Default: returns field name
@callback schema(field, schema)        # Default: returns the schema
@callback association?(field)          # Default: false
@callback assign_uploads(field, socket) # Default: returns socket unchanged
@callback before_changeset(changeset, attrs, metadata, repo, field, assigns) # 6-arity
@callback search_condition(schema_name :: binary(), field_name :: binary(), search_string :: binary()) # Default: ilike

Key Assigns Available in Templates

Example Custom Field

defmodule MyAppWeb.Fields.ColorPicker do
  @config_schema [
    palette: [
      doc: "List of allowed hex colors.",
      type: {:list, :string}
    ]
  ]

  use Backpex.Field, config_schema: @config_schema

  @impl Backpex.Field
  def render_value(assigns) do
    ~H"""
    <div class="flex items-center gap-2">
      <span class="inline-block h-4 w-4 rounded-full" style={"background-color: #{@value}"}></span>
      <span>{@value}</span>
    </div>
    """
  end

  @impl Backpex.Field
  def render_form(assigns) do
    ~H"""
    <div>
      <Layout.field_container>
        <:label align={Backpex.Field.align_label(@field_options, assigns, :center)}>
          <Layout.input_label for={@form[@name]} text={@field_options[:label]} />
        </:label>
        <BackpexForm.input
          type="color"
          field={@form[@name]}
          translate_error_fun={Backpex.Field.translate_error_fun(@field_options, assigns)}
          help_text={Backpex.Field.help_text(@field_options, assigns)}
          phx-debounce={Backpex.Field.debounce(@field_options, assigns)}
        />
      </Layout.field_container>
    </div>
    """
  end
end

Using it in a LiveResource

@impl Backpex.LiveResource
def fields do
  [
    color: %{
      module: MyAppWeb.Fields.ColorPicker,
      label: "Color",
      palette: ["#ff0000", "#00ff00", "#0000ff"]
    }
  ]
end

Declaring Fields in a LiveResource

fields/0 returns a keyword list. Each key is the Ecto schema field atom, each value is a map of options.

@impl Backpex.LiveResource
def fields do
  [
    title: %{
      module: Backpex.Fields.Text,
      label: "Title",
      searchable: true
    },
    body: %{
      module: Backpex.Fields.Textarea,
      label: "Body",
      except: [:index]
    },
    category: %{
      module: Backpex.Fields.BelongsTo,
      label: "Category",
      display_field: :name,
      searchable: true,
      live_resource: MyAppWeb.CategoryLive
    },
    inserted_at: %{
      module: Backpex.Fields.DateTime,
      label: "Created At",
      only: [:index, :show]
    }
  ]
end

Conventions

• File location: lib/my_app_web/fields/<snake_case_name>.ex
• Module naming: MyAppWeb.Fields.<FieldName>
• Always declare @config_schema before use Backpex.Field for custom field-specific options
• Use Layout.field_container and Layout.input_label in render_form/1 for consistent form layout
• Use BackpexForm.input for standard input rendering with error handling