Forem: Aline Ramos

Componente de Paginação Customizável com RubyUI + Pagy

Aline Ramos — Thu, 26 Jun 2025 13:55:28 +0000

Recentemente, comecei a desenvolver algumas aplicações menores usando o RubyUI, com o objetivo de aprender mais sobre desenvolvimento de views aproveitando ao máximo o que o Rails oferece. Este pode ser o primeiro de alguns posts onde compartilho soluções legais que consegui criar ao combinar tecnologias do ecossistema Rails para otimizar o desenvolvimento de interfaces.

Neste artigo, vou mostrar como criei uma view de paginação reutilizável, usando os componentes do RubyUI junto com a gem Pagy.

Obs.: O Pagy já oferece helpers prontos para uso direto em HTML/ERB, mas achei interessante criar meu próprio componente para poder estilizar a paginação do meu jeito e criar variações conforme as necessidades do projeto.

Pré-requisitos

Instalar o RubyUI.
Adicionar gem Pagy (por motivos de performance, é a gem mais indicada atualmente para paginação).
gem 'pagy', '~> 9.3'
Adicionar alguma biblioteca de icons (escolhi a lucide_icon, mas fica a critério de vocês).
gem 'lucide-rails', '~> 0.5.1'

Implementação

Importei os componentes prontos de Paginação e Botões.

rails g ruby_ui:component Button
rails g ruby_ui:component Pagination

Configurei as bibliotecas no Views::Base (considerando que Components::Base contém as configurações do RubyUI e Phlex para rodar os componentes).

# app/views/base.rb

class Views::Base < Components::Base
  include Pagy::Frontend

  register_output_helper :lucide_icon
end

Criei um componente Wrapper para setar padrões de div e adicionei a ele um específico com o formato para paginação (esse passo é opcional e pode ser adicionado direto na view que desejar).

module RubyUI
  class Wrapper < Base
    VARIANTS = %i[... pagination].freeze

    def initialize(variant: :default, **attrs)
      @variant = variant.to_sym
      super(**attrs)
    end

    def view_template(&block)
      case @variant
        (...)
      when :pagination then pagination_wrapper(&block)
      end
    end

    (...)

    def pagination_wrapper(&block)
      div(class: 'mt-6', &block)
    end

    (...)
  end
end

Então criei uma partial app/views/shared/pagination.rb

# app/views/shared/pagination.rb

module Views
  module Shared
    class Pagination < Views::Base
      def initialize(pagy:, request:)
        @pagy = pagy
        @request = request
      end

      def view_template
        return if @pagy.pages <= 1

        Wrapper(variant: :pagination) do
          Pagination do
            PaginationContent do
              render_first_page
              render_prev_page
              render_pages
              render_next_page
              render_last_page
            end
          end
        end
      end

      private

      def request
        @request
      end

      def render_first_page
        return if @pagy.page == 1

        PaginationItem(href: pagy_url_for(@pagy, 1)) do
          lucide_icon('chevrons-left')
        end
      end

      def render_prev_page
        return if @pagy.prev.nil?

        PaginationItem(href: pagy_url_for(@pagy, @pagy.prev)) do
          lucide_icon('chevron-left')
        end
      end

      def render_pages
        current_page = @pagy.page
        total_pages = @pagy.pages

        pages_to_show = [
          current_page - 1,
          current_page,
          current_page + 1
        ].select { |page| page.between?(1, total_pages) }

        pages_to_show.each do |page|
          PaginationItem(href: pagy_url_for(@pagy, page), active: page == current_page) { page.to_s }
        end
      end

      def render_next_page
        return if @pagy.next.nil?

        PaginationItem(href: pagy_url_for(@pagy, @pagy.next)) do
          lucide_icon('chevron-right')
        end
      end

      def render_last_page
        return if @pagy.page == @pagy.pages

        PaginationItem(href: pagy_url_for(@pagy, @pagy.pages)) do
          lucide_icon('chevrons-right')
        end
      end
    end
  end
end

Ao final, a paginação aparecerá assim:

Ela é customizável, portanto, basta remover ou adicionar algo ao view_template definido. Por exemplo, se não quiser as setas de Início e Final, basta remover os renders render_last_page e render_first_page.

(...)

      def view_template
        return if @pagy.pages <= 1

        Wrapper(variant: :pagination) do
          Pagination do
            PaginationContent do
              render_prev_page
              render_pages
              render_next_page
            end
          end
        end
      end

(...)

A visualização ficará assim:

É possível adicionar texto também, configurando os PaginationItem, como no exemplo:

(...)

      def render_prev_page
        return if @pagy.prev.nil?

        PaginationItem(href: pagy_url_for(@pagy, @pagy.prev)) do
          lucide_icon('chevron-left')
          plain "Prévia"
        end
      end

(...)

A visualização ficará assim:

Uso

Pode configurar seguindo o padrão do pagy em seu Controller:

  # Wrap your collections with pagy in your actions
  @pagy, @records = pagy(Record.all)

E você pode chamar a partial passando o @pagy e o request (que já vai por padrão no controller), exemplo:


render Views::Shared::Pagination.new(pagy: @pagy, request: request)

Um controller simples ficaria assim:

class PostController < ApplicationController
  def index
    @pagy, @posts = pagy(Post.all, limit: 42)

    render Views::Shared::Pagination.new(pagy: @pagy, request: request)
  end
end

Obrigada pela leitura! Qualquer dúvida ou módulo que achem relevante de ser adicionado, fiquem a vontade para compartilhar.
Lembrando que para ser mais concisa, não mostrei detalhes de instalação e configuração de algumas coisas necessárias, mas basta seguir os tutoriais detalhados de cada ferramenta.

Ferramentas:

RubyUI: https://rubyui.com/
Pagy: https://github.com/ddnexus/pagy
LucideRails: https://github.com/heyvito/lucide-rails

Como criei um componente Phlex usando RubyUI

Aline Ramos — Sun, 22 Jun 2025 16:32:10 +0000

Depois do anúncio do RubyUI e da ideia de escrever views 100% em Ruby, resolvi colocar em prática meus (ainda poucos) conhecimentos de componentização de views.

O objetivo era criar um componente simples e reutilizável de Título de Seção (SectionHeader) para usar na minha aplicação, como no exemplo abaixo:

Abaixo, vou mostrar o passo a passo de como fiz, usando componentes prontos do RubyUI e um pouco de TailwindCSS para estilizar.

1. Construindo o esqueleto da view:

A estrutura de componentes do RubyUI já existia no projeto, então criei um novo arquivo chamado section_header.rb dentro da pasta de componentes. O componente herda de uma classe Base, que por sua vez herda de Phlex::HTML — ou seja, tudo aqui é Ruby puro, sem HTML no meio!

E o esqueleto do componente segue o padrão de renderização do Phlex.

# app/components/ruby_ui/section_header/section_header.rb

module RubyUI
  class SectionHeader < Base
    def initialize()
      # onde se recebe os parâmetros para montar a view
    end

    def view_template
      # onde montamos a página
    end
  end
end

2. Exibindo o título

O primeiro passo foi permitir que o componente recebesse um título como parâmetro e exibisse esse título usando o componente Heading do RubyUI (que faz parte do grupo de componentes de Typography).

rails g ruby_ui:component Typography

# app/components/ruby_ui/section_header/section_header.rb

module RubyUI
  class SectionHeader < Base
    def initialize(title: ")"
      @title = title
    end

    def view_template
      Heading(level: 2) { @title }
    end
  end
end

Assim, já sou capaz de chamar o componente da seguinte forma:

  SectionHeader.new(title: "\"Usuários\")"

3. Adicionando estilo com Tailwind

Para deixar o título mais destacado, envolvi o Heading em uma div com algumas classes do TailwindCSS, criando uma borda inferior e espaçamento:

# app/components/ruby_ui/section_header/section_header.rb

module RubyUI
  class SectionHeader < Base
    def initialize(title: ")"
      @title = title
    end

    def view_template
      div(class: "border-b border-gray-200 pb-5 mb-5") do
        Heading(level: 2) { @title }
      end
    end
  end
end

O resultado é este, já com comportamento para dark e light mode:

4. Tornando o componente mais flexível

Pensei: e se eu quiser adicionar um botão de ação, como "Criar novo"? Para isso, adicionei mais dois parâmetros opcionais: href (link do botão) e label (texto do botão). Usei o componente Link do RubyUI para criar o botão, mas você pode trocar por um Button se preferir.

Link

rails g ruby_ui:component Link

Button

rails g ruby_ui:component Button

# app/components/ruby_ui/section_header/section_header.rb

module RubyUI
  class SectionHeader < Base
    def initialize(title: ", href: nil, label: nil)"
      @title = title
      @href = href
      @label = label
    end

    def view_template
      div(class: "border-b border-gray-200 pb-5 mb-5") do
        div(class: "sm:flex sm:items-center sm:justify-between ml-3") do
          Heading(level: 2) { @title }
          if @href
            div(class: "mt-3 sm:mt-0 sm:ml-4") do
              Link(href: @href, variant: :primary, size: :lg) { @label }
            end
          end
        end
      end
    end
  end
end

Agora, para exibir o título com um botão de ação, basta chamar assim:

SectionHeader.new(
  title: "\"Usuários\","
  href: new_admin_user_path,
  label: "Criar Usuário"
)

O resultado final é:

Dicas extras

Você pode evoluir o componente para receber a chave de tradução do I18n no lugar do texto do título, facilitando a internacionalização.
O mesmo padrão pode ser usado para outros tipos de header, mudando só os componentes internos.

Com isso, ficou fácil criar headers de seção bonitos e padronizados, só usando Ruby e os componentes do RubyUI. Se quiser ver mais exemplos, recomendo dar uma olhada na documentação oficial do RubyUI.
Se ficou alguma dúvida ou quiser trocar ideia, só comentar!

Links de referência:

Phlex: https://www.phlex.fun/components/rendering.html
RubyUi: https://rubyui.com

How I Built a Phlex Component Using RubyUI

Aline Ramos — Sun, 22 Jun 2025 16:07:21 +0000

After the announcement of RubyUI and the idea of writing views 100% in Ruby, I decided to put my (still limited) knowledge of view componentization into practice.

My goal was to create a simple and reusable Section Header component to use in my app, like in the example below:

Below, I’ll walk you through the step-by-step process, using ready-made components from RubyUI and a bit of TailwindCSS for styling.

1. Building the Component Skeleton

The RubyUI component structure already existed in my project, so I created a new file called section_header.rb inside the components folder. The component inherits from a Base class, which itself inherits from Phlex::HTML—so everything here is pure Ruby, no HTML templates!

The skeleton of the component follows the Phlex rendering pattern:

# app/components/ruby_ui/section_header/section_header.rb

module RubyUI
  class SectionHeader < Base
    def initialize()
      # put the params here
    end

    def view_template
      # build your page here
    end
  end
end

2. Displaying the Title

The first step was to allow the component to receive a title as a parameter and display it using the Heading component from RubyUI (which is part of the Typography group).
rails g ruby_ui:component Typography

rails g ruby_ui:component Typography

# app/components/ruby_ui/section_header/section_header.rb

module RubyUI
  class SectionHeader < Base
    def initialize(title: ")"
      @title = title
    end

    def view_template
      Heading(level: 2) { @title }
    end
  end
end

Now, I can call the component like this:

SectionHeader.new(title: "\"Users\")"

3. Adding Tailwind Styling

To make the title stand out, I wrapped the Heading in a div with some TailwindCSS classes, adding a bottom border and spacing:

# app/components/ruby_ui/section_header/section_header.rb

module RubyUI
  class SectionHeader < Base
    def initialize(title: ")"
      @title = title
    end

    def view_template
      div(class: "border-b border-gray-200 pb-5 mb-5") do
        Heading(level: 2) { @title }
      end
    end
  end
end

The result already works for both dark and light mode:

4. Making the Component More Flexible

Then I thought: what if I want to add an action button, like “Create New”? For that, I added two more optional parameters: href (the button link) and label (the button text). I used the RubyUI Link component to create the button, but you could swap it for a Button if you prefer.

Link

rails g ruby_ui:component Link

Button

rails g ruby_ui:component Button

# app/components/ruby_ui/section_header/section_header.rb

module RubyUI
  class SectionHeader < Base
    def initialize(title: ", href: nil, label: nil)"
      @title = title
      @href = href
      @label = label
    end

    def view_template
      div(class: "border-b border-gray-200 pb-5 mb-5") do
        div(class: "sm:flex sm:items-center sm:justify-between ml-3") do
          Heading(level: 2) { @title }
          if @href
            div(class: "mt-3 sm:mt-0 sm:ml-4") do
              Link(href: @href, variant: :primary, size: :lg) { @label }
            end
          end
        end
      end
    end
  end
end

Agora, para exibir o título com um botão de ação, basta chamar assim:

SectionHeader.new(
  title: "'Usuários',"
  href: new_admin_user_path,
  label: 'Criar Usuário'
)

The final result looks like this:

Extra Tips

You can improve the component to accept an I18n translation key instead of a plain string for the title, making internationalization easier.
You can use the same pattern for other types of headers, just by changing the internal components.

With this, it’s super easy to create beautiful, standardized section headers using only Ruby and RubyUI components. If you want to see more examples, I recommend checking out the official RubyUI documentation.
If you have any questions or want to chat, just leave a comment!

Links and references:

Phlex: https://www.phlex.fun/components/rendering.html
RubyUi: https://rubyui.com