Theo is a small and elegant HTML-like template language for Ruby on Rails, featuring natural partials and computed attributes.

Thanks to Hotwire, it's now possible to build sophisticated server-rendered user interfaces in Ruby on Rails. However, ERB, Rails' most popular template language, has unintuitive partial syntax, especially for those used to working with Vue.js or React components.

With Theo, you can render a partial using HTML-like syntax:

<_button size="large" label%="label" />

Run

gem install theo-rails

If you are using TailwindCSS, add .theo extension to the content key in your tailwind.config.js:

'./app/views/**/*.{erb,haml,html,slim,theo}'

Computing attribute value in ERB feels awkward because angle brackets <> clash with the surrounding HTML tag.

In Theo, an attribute with computed value can be expressed using %=. For example:

<a href%="root_path">Home</a>

is equivalent to:

<a href="<%= root_path %>">Home</a>

Rendering a partial in ERB requires switching between HTML markup and Ruby code, and the render verb makes it difficult to imagine a page as a component structure.

In Theo, you render a partial by writing a tag with _ prefix, for example:

<_button size="large" />`

is equivalent to:

<%= render 'button', size: 'large' %>

Naturally, partials can also include content, e.g.:

<_button size="large">
  Create
</_button>

You can render a collection of partials as follows:

<_widget collection="widgets" />

which is equivalent to:

<%= render partial: 'widget', collection: widgets %>

You can also customize the local variable name via the as attribute, e.g.:

<_widget collection="widgets" as="item" />

If an attribute has no value, you can omit it, for example:

<_button disabled />

is equivalent to:

<_button disabled="" />

To render a partial from another folder, use the 'path' attribute, e.g.:

<_widget path="widgets" />

is equivalent to:

<%= render 'widgets/widget' %>

Partials can yield a value, such as a builder object that can be used by child partials. For example:

<_widget_builder yields="widget">
  <_widget_element widget%="widget" />
</_widget_builder>

is equivalent to:

<%= render 'widget_builder' do |widget| %>
  <%= render 'widget_element', widget: %>
<% end %>

Instead of using yields attribute, a parent partial can indirectly pass a variable to its children using the provide and inject helpers. The example above can be modified as follows:

<_widget_builder>
  <_widget_element />
</_widget_builder>

_widget_builder.html.theo:

<% provide(widget:) do %>
  <%= yield %>
<% end %>

_widget_element.html.theo:

<% widget = inject(:widget) %>

You can freely mix ERB and Theo syntax, e.g.:

<% if total_amount > 100 %>
  <_free_shipping amount%="total_amount" />
<% end %>

You can build a <form> element in ERB using ActionView form helpers. Theo provides corresponding partials. For example:

<_form_with model%="widget" data-turbo-confirm="Are you sure?">
  <div>
    <_label name="name" />
    <_text_field name="name" />
  </div>

  <div>
    <_label name="size" />
    <_select name="size" options%="['Big', 'Small']" />
  </div>

  <_submit value="Create" />
</_form_with>

is equivalent to:

<%= form_with model: widget, data: { turbo_confirm: 'Are you sure?' } do |form| %>
  <div>
    <%= form.label :name %>
    <%= form.text_field :name %>
  </div>

  <div>
    <%= form.label :size %>
    <%= form.select :size, ['Big', 'Small'] %>
  </div>

  <%= form.submit "Create" %>
<% end %>

Theo is compatible with ViewComponent framework.

Here's a component using Theo template syntax:

class ButtonComponent < ViewComponent::Base
  theo_template <<-THEO
    <span class%="@size"><%= content %></span>
  THEO

  def initialize(size:)
    @size = size
  end
end

Component can be rendered from Theo template using the following syntax:

<Button size="large" />

which is equivalent to:

<%= render(ButtonComponent.new(size: "large")) %>

Components can also include content:

<Button size="large">
  Create
</Button>

and yield a value:

<Button size="large" yields="component">
  <% component.with_header do %>Icon<% end %>
  Create
</Button>

You can also render a component collection as follows:

<Widget collection="widgets" />

which is equivalent to:

<%= render WidgetComponent.with_collection(widgets) %>