StimulusRailsDatatables

A comprehensive Rails gem that provides DataTables integration with server-side processing, advanced filtering, and Stimulus controllers for modern Rails applications.

Features

Server-side DataTables: Full integration with ajax-datatables-rails
Advanced Filtering: Dynamic filters with dependent selects and date ranges
Stimulus Controllers: Modern JavaScript integration using Hotwire Stimulus
Bootstrap 5 Support: Beautiful, responsive tables out of the box
LocalStorage State: Filter and table state persistence
Flexible API: Easy-to-use Ruby helpers and JavaScript API

Installation

Add this line to your application's Gemfile:

gem 'stimulus_rails_datatables'

And then execute:

$ bundle install

Usage

Helpers

Basic DataTable

<%= datatable_for 'users-table', source: users_path do |dt| %>
  <% dt.column :id, title: 'ID' %>
  <% dt.column :name, title: 'Name' %>
  <% dt.column :email, title: 'Email' %>
  <% dt.column :created_at, title: 'Created', orderable: false %>
<% end %>

With Filters

<%= filter_for 'users-table' do |f| %>
  <%= f.status do |opts| %>
    <%= opts.option '', 'All Statuses' %>
    <%= opts.option 'active', 'Active' %>
    <%= opts.option 'inactive', 'Inactive' %>
  <% end %>

  <%= f.role(
    remote: {
      url: roles_path,
      label: 'name',
      value: 'id',
      placeholder: 'Select Role'
    }
  ) %>

  <%= f.duration do |opts| %>
    <%= opts.option '', 'All Time' %>
    <%= opts.option 'today', 'Today' %>
    <%= opts.option 'this_week', 'This Week' %>
    <%= opts.option 'custom', 'Custom Range' %>
  <% end %>
<% end %>

Backend DataTable Class

class UserDatatable < StimulusRailsDatatables::BaseDatatable
  def view_columns
    @view_columns ||= {
      id: { source: "User.id" },
      name: { source: "User.name" },
      email: { source: "User.email" },
      created_at: { source: "User.created_at" }
    }
  end

  def data
    records.map do |record|
      {
        id: record.id,
        name: record.name,
        email: record.email,
        created_at: record.created_at.strftime('%Y-%m-%d')
      }
    end
  end

  def get_raw_records
    User.all.then { |relation| apply_filters(relation) }
  end

  private

  def apply_filters(relation)
    relation = relation.where(status: query_filters[:status]) if query_filters[:status].present?
    relation = relation.where(role_id: query_filters[:role_id]) if query_filters[:role_id].present?
    relation
  end
end

JavaScript API

// Reload a specific datatable
AppDataTable.reload('#users-table')

// Load with new URL
AppDataTable.load('#users-table', '/users?status=active')

// Reload all datatables on page
AppDataTable.reloadAll()

Configuration

The gem automatically registers Stimulus controllers and imports required JavaScript dependencies. The following controllers are available:

datatable - Main DataTable controller
filter - Filter controller with state management

Overriding Default Configuration

To override the default DataTables configuration, create a file at app/javascript/datatables_config.js with your custom settings or run rails generator:

rails generate stimulus_rails_datatables:install

Once created, you can pin it in your importmap configuration:

# config/importmap.rb
pin 'datatables_config', to: 'datatables_config.js'

Finally, import it in your application JavaScript:

// app/javascript/application.js
import 'datatables_config'

Note: You may need to restart your Rails server for changes to take effect.

Dependencies

Rails >= 7.0
ajax-datatables-rails ~> 1.4
importmap-rails
@hotwired/stimulus
DataTables.net with Bootstrap 5 theme

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/denmarkmeralpis/stimulus_rails_datatables.

License

The gem is available as open source under the terms of the MIT License.