Phlex Views & Components

Components are Ruby objects — no template language, no DSL. Views replace ERB templates (one per controller action). Components are reusable UI building blocks.

Core Workflow

1. Use the scaffold generator — custom PhlexControllerGenerator produces

Phlex views instead of ERB. See [reference/coding-phlex.md § Scaffolding](reference/coding-phlex.md) for the full generator code and all 5 templates.

1. Implementation order — models → controllers → views/components → tests.
2. Forms default to ERB partials — Rails form builders are ergonomic there.

Phlex form helpers exist for simple cases.

Class Hierarchy

Components::Base < Phlex::HTML   (include Components, route helpers, dev comments)
  ├── Views::Base                (+ Debug, ContentFor, caching)
  ├── Components::Layout         (+ Phlex::Rails::Layout)
  └── Components::PageHeader, TitleBar, List, GridCell, ...

# app/components/base.rb
class Components::Base < Phlex::HTML
  include Components
  include Phlex::Rails::Helpers::Routes

  if Rails.env.development?
    def before_template
      comment { "Before #{self.class.name}" }
      super
    end
  end
end

# app/views/base.rb
class Views::Base < Components::Base
  include Phlex::Rails::Helpers::Debug

  def cache_store = Rails.cache
end

Short-form Component Calls

include Components on the base class enables method-style rendering:

# Instead of:
render Components::PageHeader.new(title: "Labels")

# Write:
PageHeader(title: "Labels")

Component Slots via Methods

Public methods on components yield named content areas:

class Components::TitleBar < Components::Base
  def view_template(&) = div(class: "title-bar", &)
  def leading_action(&) = div(class: "leading-action", &)
  def title(&) = h1(&)
  def actions(&) = div(class: "actions", &)
end

# Usage:
render Components::TitleBar.new do |bar|
  bar.leading_action { link_to("Back", labels_path) }
  bar.title { "My Page" }
  bar.actions { button_to("Delete", @label, method: :delete) }
end

Helper Includes

Include only the Phlex::Rails::Helpers::* each view needs — never on Base:

class Views::Labels::Show < Views::Base
  include Phlex::Rails::Helpers::ContentFor
  include Phlex::Rails::Helpers::DOMID
  include Phlex::Rails::Helpers::ButtonTo
  include Phlex::Rails::Helpers::LinkTo
  include Phlex::Rails::Helpers::TurboFrameTag
  # ...
end

Common helpers: Routes, ContentFor, DOMID, ButtonTo, LinkTo, TurboFrameTag, TurboStreamFrom, ImageTag, ClassNames, Request, Notice, Debug, Sanitize, StripTags.

Content Areas

Layout yields named areas; views populate via content_for:

content_for :title, "Labels"

content_for :main_header do
  render Components::PageHeader.new do |header|
    header.title_bar { |bar| bar.title { "Labels" } }
  end
end

content_for :floating_action do
  render Components::FloatingActionMenu.new
end

Standard areas: :title, :mainheader, :floatingaction, :head.

Controller Rendering

Controllers render Phlex views directly, passing data via new:

class LabelsController < ApplicationController
  def index
    @pagy, @labels = pagy(Label.all)
    render Views::Labels::Index.new(@labels, @pagy)
  end

  def show
    render Views::Labels::Show.new(@label)
  end

  def create
    @label = Label.new(label_params)
    if @label.save
      redirect_to @label, notice: "Label was successfully created."
    else
      render Views::Labels::New.new(@label), status: :unprocessable_entity
    end
  end
end

Custom Element Wrappers

Use register_element for web component custom elements (Web Awesome, Shoelace, etc.):

module Components::MyLibrary
  class MyButton < Phlex::HTML
    register_element :my_button  # renders <my-button>

    def initialize(variant: "neutral", size: "medium", **attributes)
      @attributes = attributes.with_defaults(variant: variant, size: size)
    end

    def view_template(&) = my_button(**@attributes, &)
  end
end

Use phlexcustomelementgenerator to auto-generate wrappers from custom element manifests.

register_output_helper :vite_client_tag       # returns HTML
register_output_helper :vite_javascript_tag
register_output_helper :column_chart          # chartkick
register_value_helper :alert                  # returns a value

# In a Phlex view:
section { render partial("form", label: @label) }

# The ERB partial uses standard form_with / form_for

def view_template
  cache("labels/#{@label.id}/card") {
    # expensive rendering
  }
end

class Components::Layout < Components::Base
  include Phlex::Rails::Layout
  # app shell
end

class Components::MarketingLayout < Components::Base
  include Phlex::Rails::Layout
  # landing pages
end

div(data: {
  controller: "faceted-search",
  action: "input->faceted-search#perform:prevent",
  faceted_search_url_value: labels_path
}) { ... }

turbo_frame_tag(album, src: album_path(album), loading: :lazy) {
  render Components::Spinner.new
}

turbo_stream_from([@budget, :items])

# In layout <head>:
meta name: "turbo-refresh-method", content: "morph"
meta name: "turbo-refresh-scroll", content: "preserve"

class Views::Labels::Index < Views::Base
  include Pagy::Frontend

  def initialize(labels, pagy)
    @labels = labels
    @pagy = pagy
  end

  def view_template
    # ... render labels ...
    raw safe(pagy_nav(@pagy))
  end
end