Table

A table displays rows of data.

Show be used to display a collection of structured data, and to sort, search, paginate and filter data.

Related components

✅ Do

Order rows intuitively

Data should be initially rendered in an intuitive order. For example, starting with the most recently created items. By default, sort alphabetically by the first column's content.

Keep column headers short and consistent

Column headers are short labels used to define the kind of data that is shown in that column. If we already have similar column content, use same logica column header name.

Use “skeleton” placeholders to indicate loading content

When the content of the table is still loading, show a skeleton placeholder, this will improving the user experience by reducing uncertainty during loading times.

Communicate when the table has no data to show

If there is no data available for display in the table, present the table empty state within the table body.

Use correct column types

Before creating your table, please make sure that you use the appropriate types, to ensure that the correct components are being used.

❌ Don't

Don't use a single column to show multiple pieces of data

The column header should accurately represent the data point rendered in the column's cells. It would also be unclear which data point is being used when sorting or filtering.

Description

The Table component is used to display data in a tabular format. It is a wrapper around the Ant Design Table component.

Arguments

The data also supports all basic data types, including strings, HTML strings, and ViewComponent objects.

If a response or hydrated payload provides a non-array value for data (for example null), the component now safely falls back to an empty array to avoid runtime errors during rendering.

Expandable Config schema

The expandable config follows the same structure as the Ant Design Table Expandable config. But currently only three keys are supported:

• default_expanded_row_keys: An array of keys that will be expanded by default.
• default_expand_all_rows : A boolean that will expand all rows by default. True will make all rows expanded, false will make all rows collapsed.
• indent_size: The indentation value for children columns. No default. If present, overrides the deprecated tree_indent_size parameter.

Column Object

Columns is a hash, that accepts the following parameters:

• title: The column title. This can be a simple string, or any HTML element.
• dataIndex: The key of the data object. This key will be used as the key to create the payload for sort and filter requests.
• key: The key of the column. This is used to check what property of the data row will be used to render the contents of the cell.
• type: Optional parameter, currently only supports two values, the value "html"/:html, and the value "date"/:date. This will render the cell as HTML, without escaping the contents. If it's type :date, the column will automatically render a DateShow component with the string that was passed through.

These are the optional parameters:

• sortable: Optional parameter, must be true or false. Defaults to false. This will make the column sortable.
• searchable: Toggles the search input for the column. Defaults to true.
• default_sort: Sets the default sort state for the column. Can be :asc or :desc. Doesn't actually sort the colum, the data must come already sorted.
• sort_key: Optional parameter. Sets the key for sorting. The key is the name of the parameter that will be sent to the server. Defaults to dataIndex.
• hidable: Optional parameter, must be true or false. Defaults to true. This will make the column hidable.
• filters: Optional parameter, must be an array of objects. The schema is defined below. The presence of this key will make the column filterable.
• async_filter: Optional parameter, must be a hash. Enables async filter loading from a JSON endpoint. Currently this only works with flat filters; nested/tree filters are not supported in async mode. Useful for large filter sets where sending all filter options in the initial HTML would be too expensive.
• empty_filter: Optional parameter. If true, will add en empty filter option with value _blank. You can customize the empty value by passing a hash with a value key, eg: empty_filter: { value: "none" }.
• filter_type: Optional parameter. Sets the type for all filters.
• filter_key: Optional parameter. Sets the key for all filters. The key is the name of the parameter that will be sent to the server.
• width, min_width, max_width: Optional parameters. Sets the inline style for width, minWidth and maxWidth respectively for the cell content. The value is in pixels.
• fixed: Optional parameter. Accepts "left". Makes the column stick to the left side of the table.

Configure the column width

The Table will always take maximum width available, and distribute the columns to fit the content by default. You can set the width of the cell contents by using the width, min_width, and max_width parameters. Columns with a width lesser than the content will be truncated with ellipsis ('...'), and a tooltip will be shown with the full content. Note that this should only be set on columns that need to have fixed widths with text content, although it will work on any column, only the innerText will be displayed in the tooltip. Also, these parameters will only affect the cell content, and not the header content. You can experiment with this setting in the treewithrowrender_ example.

Sometimes you may want to have trucated text in cells where the content also has other HTML tags. In these cases, you can use the CSS class lui-table_cell--text, for example:

<% row.with_cell(property: :name) do %>
    <div class="flex gap-2">
        <%= render LooposUi::Image.new(image_url: presenter.image, size: "small") %>
            <%= link_to(
                presenter.name,
                presenter.show_path,
                data: { turbo_frame: 'lui-main-layout', turbo_action: :advance}, class: "lui-table_cell--text") %>
    </div>
<% end %>

Filter object schema

The filters parameter's type should be the symbolized name of the component class it represents, or one of the following: :entity, :tag, if the column does not represent a model in the system. Eg: Catalog::Product should be :catalog_product, or just :product.

dataIndexs value will be used to generate the payloads for sorting and filtering.

Example:

# Column definition
columns = [
    {
        title: "Type",
        dataIndex: :type,
        key: :type,
        sortable: true,
        filters: [
            { type: :tag, text: "Fire", value: "fire" },
            { type: :tag, text: "Water", value: "water" },
            ...
        ]
    }
    ...
]

Async filters

For columns with many filter options, you can use async_filter instead of filters.

async_filter currently supports flat filters only. If your filters use children (tree/nested filters), keep using the regular static filters option.

This keeps the table backwards compatible:

• Use filters for small static filter lists.
• Use async_filter for large flat filter lists that should be fetched lazily.

The table will:

• Fetch the first page of filters when the table loads.
• Reuse those options when the dropdown is opened.
• Fetch the next page when the user scrolls to the bottom of the dropdown.
• Fetch from page 1 again when the user searches inside the filter dropdown.

Current limitations:

• Async filters currently support flat filters only.
• Filters with children are not supported in async mode.
• Tree/nested filters should still use the regular filters option.

async_filter schema

Example:

columns = [
  {
    title: "Ability",
    dataIndex: :ability,
    key: :ability,
    type: :html,
    filter_key: :ability,
    async_filter: {
      url: filter_options_pokemons_path,
      initial_page_size: 25,
      page_size: 25
    }
  }
]

The endpoint must return JSON in the following format:

{
  "filters": [
    { "type": "tag", "text": "Blaze", "value": "Blaze" },
    { "type": "tag", "text": "Overgrow", "value": "Overgrow" }
  ],
  "pagination": {
    "page": 1,
    "page_size": 25,
    "total_count": 269,
    "has_more": true,
    "next_page": 2
  }
}

Notes:

• The filters array follows the same flat filter object schema documented below.
• The selected values still generate the same query payload as static filters, for example q[ability][]=Blaze.
• If you use filter_key, that key will still be used in the outgoing filter params.

Global filter object schema:

Example for the query generated by the filters and sorting:

# When sorting (ascending), will generate the query:
sort_by=type:asc
# When sorting (ascending), will generate the query:
# if you declare a sort_key, it will be used instead of the dataIndex
# sort_key: :type_name
sort_by=type_name:asc
# When searching for "Fire", will generate the query:
q[search]=Fire
# When filtering, selecting Both "Fire" and "Water"
q[type][]=fire
q[type][]=water

Although it's not advised, the filters also support filtering with heterogeneous data, like Partner and PartnerGroup filters, on the same column. The alternative would be to implement a PartnerGroup column, and a Partner column, and filter them separately, or to handle such cases in the backend, by having some generic Partnable model. In any case, here is an example of how to handle such cases:

# Example of heterogeneous data (Partner, and PartnerGroups filters)
columns = [
    {
        title: "Partner",
        dataIndex: "partner_name",
        type: :html,
        sortable: true,
        filter_key: :partner_ids,
        filters: Partner.all.map { |partner|
            { text: partner.name, value: partner.id } } +
            PartnerGroup.all.map { |group|
            { text: group.name, value: group.id, key: :partner_group_ids } }
    }
]
# When filtering, selecting some partner, and some partner group, will generate the following query:
q[partner_ids][]=1
q[partner_ids][]=2
q[partner_group_ids][]=3

By default, the dataIndex will be used as the key for the filter, but this can be overriden by the filter_key parameter, and the key parameter in the filter object. The app decides how to handle these filters (should they be ORed, ANDed, etc).

⚠️ Warning: To prevent the filter results showing up empty, when using this method remember to use data RELATED to the subject of the table, not global data. Per example, if we wanted to do a table of brands, instead of doing this:

Product.all.map { |product| { text: product.name, value: product.id } }

We can do something like this:

Product.joins(:brand).distinct.map { |product| { text: product.name, value: product.id } }

That way, only products that are relevant will appear, making it so that we will always show results in the table.

Tree Table

(Slotted mode) You can also create a Tree Table by using the with_child slot on the row object. Refer to the tree example.

But more often than not, you will want to render a recursive tree, where manually defining the children is not feasible without knowing the depth of the tree. For these cases, it's recommended to use the the tree_render method on the row ViewComponent.

To use it, you must define a render function (refer to the tree with row render example). The main difference is that the function is defined in ruby, and not pre-precessed with .erb.

Note: Some caveats: due to how the ViewComponents are rendered, you cannot render objects in sequence. If you need to do so, you will have to concatenate them. You can do so using the concat method.

Then, when rendering the cable, call the tree_render method, and pass in:

• The data object
• A function that returns the children of the object
• A function that returns the key for the row given the object (and optionally the list of parent objects, sorted by ascending level)
• The render function

You also have access to the row object, so you can use it's methods to manipulate it's state. This is useful for example to set row_data.

Example:

# Define the render function
def render_function(row, data, level = 0)
    row.row_data = { ... }
    row.with_cell(property: :name) do
        # ...
    end
    row.with_cell(property: :features) do
        tag.span(class: "flex gap-2") do
            # Concatenating the objects
            concat render(LooposUi::Token.new(text: "Level #{level}")) # Important
            concat render(LooposUi::Token.new(text: "Another token"))  # Otherwise only the last statement will render
        end
    end
    row.with_action do
        render(LooposUi::Button.new(
            #...
        ))
    end
end

# Render the tree
<%= render LooposUi::V2::Table.new(**options) do |table| %>
    <% data.each_with_index do |category, i| %>
        <% table.with_row(key: "#{category[:name]}_#{i}}") do |row| %>
            <% row.tree_render(
                category,
                get_children_fn: proc { |c| c[:children] },
                key_fn: proc { |c,level| "#{c[:name]}_#{level}" },
                render_row_fn: method(:render_function)
            )%>
        <% end %>
    <% end %>
<% end %>

Check the provided example for more information (tree with row render)

Search

The search input, located at the top right side of the table, will send a query to the server with the key q[search] and the value of the search input.

Slots

This component has two modes of usage, with arguments (data, columns, pagination) or with slots.

Slots Mode: When using the slots mode, only the columns argument is required.

Argument Mode: When using the argument mode, the columns and data arguments are required. Prefer the Slots Mode, most of the time argument mode will not be enough.

Argument Mode

Check Ant Design docs for more information about columns and data.

Example of column and data arguments:

columns = [
    { title: "ID", dataIndex: "id", key: "id" },
    { title: "Name", dataIndex: "name", key: "name", type: "html"},
    { title: "Type", dataIndex: "type", key: "type", type: "html" },
    { title: "HP", dataIndex: "hp", key: "hp" },
    { title: "Attack", dataIndex: "attack", key: "attack" },
    { title: "Defense", dataIndex: "defense", key: "defense" },
    { title: "Speed", dataIndex: "speed", key: "speed" },
    { title: "Ability", dataIndex: "ability", key: "ability", type: "html" }
]
pokemon_data = [
  {
    id: 1,
    name: "Bulbasaur",
    type: ["Grass", "Poison"],
    hp: 45,
    attack: 49,
    defense: 49,
    speed: 45,
    ability: "Overgrow"
  }
  #...
]

Slots Mode

When in slots mode, only the columns argument is required.

The data is defined within the slots using with_row and with_cell methods.

Row arguments

Each row must have a unique key attribute, while each cell must have a property attribute that matches the dataIndex of the column.

Note, the row key attribute must be unique, and will be used to identify the row when selecting it.

Following is an example on how these rows could be defined:

<%= render LooposUi::V2::Table.new(pagination: pagination, columns: columns, **options) do |table| %>
    <% pokemon_data.each do |pokemon| %>
        <% table.with_row(key: pokemon.id) do |row| %>
            <% row.with_cell(property: :id).with_content(pokemon.id.to_s) %>
            <% row.with_cell(property: :name) do %>
                <%= tag.div( pokemon.name,  class: "text-secondary-base-bold") %>
            <% end %>
            <% row.with_cell(property: :type) do %>
                <div class="flex gap-2">
                    <% pokemon.type.each do |type| %>
                        <%= render LooposUi::TagToken.new(text: type, color: LooposUi::TagToken::COLORS.keys.sample ) %>
                    <% end %>
                </div>
            <% end %>
            <% row.with_cell(property: :hp).with_content(pokemon.hp.to_s) %>
            <%#... %>
            <% row.with_cell(property: :ability) do  %>
                <% tag.span(id: "pokemon_#{pokemon.id}_ability") do %>
                    <%= render LooposUi::Tooltip.new(title: pokemon.ability, tippy_target_id: "pokemon_#{pokemon.id}_ability") do |tooltip| %>
                        <% tooltip.with_description {Faker::Lorem.paragraphs.join} %>
                        <% tooltip.with_button(text: "Bulbapedia", leading_icon: "fa-regular fa-link", href: "#", type: :secondary, size: :tiny) %>
                    <% end %>
                    <%= render LooposUi::CounterLabel.new(text: pokemon.ability, icon: "fa-regular fa-info-circle") %>
                <% end %>
            <% end %>
        <% end %>
    <% end %>
<% end %>

Row actions

The Slots Mode also supports actions. When adding actions on a row, using the with_action slot, the table will render a new column that is only visible when hovering over the row.

Note: Currently the actions is an open slot, meaning that it can accept any content. However, it is recommended to use the Button component, and this may change in the future, making it mandatory.

<# ... >
<% row.with_action do %>
    <%= render LooposUi::Button.new(icon: "fa-regular fa-edit", type: :secondary, kind: :neutral )%>
<% end %>
<% row.with_action do %>
    <%= render LooposUi::Button.new(icon: "fa-regular fa-trash", type: :secondary, kind: :neutral )%>
<% end %>
<# ... >

Row actions can include tooltips and disabled states, for example:

<%= render LooposUi::Button.for_row_action(
  icon: "candy",
  tooltip_text: "Add 10 levels",
  disabled: pokemon.level + 10 > Pokemon::MAX_LEVEL
) %>

Footer

You can also set a custom footer using the with_footer(**kwargs) slot. Any kwargs passed in will be forwarded to a wrapper div element that will hold your footer content. It's compatible with the manageable_rows - if it's set, a button to add a new row will be injected as the first child of the footer.

Eg:

<% table.with_footer(class: "w-full flex justify-between") do %>
  Some Footer Text
  <%= render LooposUi::Button.new(text: "Click me", type: :primary) %>
<% end %>

Manageable Rows

When the manageable_rows argument is set to true, the table will render a footer with a button to add new rows, and each row will also have an action to remove the row. The add_new_url argument (Table component) is mandatory when manageable_rows is set to true. Also, the delete_action argument is mandatory when defining the row.

To make this feature work, you need to:

• Set manageable_rows to true in the table definition.
• Define the add_new_url argument. Will be called (GET) when the user clicks the add new button.
• Define the delete_action argument in the row definition. Will be called when the user clicks the automatically injected delete row action.
• Create endpoints to handle the add and delete actions.

Add new row

The add_new_url endpoint must answer with a JSON object containing the new row data. Ex:

# Some controller
def table_new
    @new_row = LooposUi::V2::Table::Row.new(key: "unique key", manageable_rows: true,  delete_action: { url: "delete url" })
    render_to_string
    render(json: @new_row.data, content_type: "application/json")
end

And in the view, you must capture the output and call render_to_string in the controller.

<%# table_new.html.erb %>
<% capture do %>
  <%= render @new_row do |row| %>
    <% row.with_cell(property: :id) do %>
      <%= link_to pokemon.id, "#" %>
    <% end %>
    <%# ... %>
  <%# ... %>
<% end %>

The delete endpoint will be called, and the row will be removed regardless of the response.

Usage docs for this feature ends here, following is just an explanation as for why this is the way it is, for the curious:

You may be asking, why tho? This feels weird, and render_to_string?? 🤔 What is this?

It must be done this way because, even tough the Row in a ViewComponent, it's used only for enabling the developer to render the cells using a ViewComponent syntax. It's not meant to be rendered directly. We render the row this way (also how it's rendered internally by the table) just to populate the data object with the cell content (html), that will be then passed in as a prop to the table component. Here, it's the same process: We render the row, capture the output, collect the data and return it as JSON - this way the Table can just setData([...data, newRow]) without having to re-render the whole table.

Events

The Table component emits the following events:

• tableElementsSelected, you can access the details.selectedElements to get the selected elements.
• tableRowReorder, dispatched when a row is reordered by dragging and dropping. You can access event.detail.activeId (the ID of the dragged row) and event.detail.overId (the ID of the row it was dropped on) to handle the reordering logic.

Pagination

Pagination will only appear if there are more elements than the selected pageSize, and the selector to change page size will only appear if there are more than 15 elements. The pagination will be reset when applying a filter or sorting the table. The only valid pageSizes are 15,30 and 100. Any other value will be clamped to the nearest valid value. When the pagination is disabled, and there are more elements than the selected pageSize, a View More button will appear, that will showcase the current elements as well as the next 10. You can change the amount of rows added per click with the view_more option (default 10).

Floating Bar

The Table component can also render a floating bar at the bottom of the table when one or more rows are selected. This happens only happens if the Table has selectable set to true, uses the with_action_bar slot, and has at least one action defined.