# ajax-datatables-rails: server-side DataTables without hand written JSON > ajax-datatables-rails implements the DataTables server-side processing protocol on the Rails side, generating the JSON that jQuery DataTables expects from a declarative column mapping. It is ActiveRecord only, and its newest release is from 2024. **jbox-web/ajax-datatables-rails** — A wrapper around DataTable's ajax methods that allow synchronization with server-side pagination in a Rails app - Repository: https://github.com/jbox-web/ajax-datatables-rails - Stars: 601 · Forks: 221 - Language: Ruby - License: MIT - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/jbox-web-ajax-datatables-rails ## The gap server-side pagination leaves behind DataTables is a jQuery plugin that adds the ability to paginate, sort and search your html tables. The README is direct about where that stops working. When dealing with large tables, more than a couple of hundred rows, you run into performance issues, and those can be fixed by using server-side pagination, but that breaks some DataTables functionality. That break is the whole reason this gem exists. The project describes itself as a wrapper around the DataTables ajax methods that allows synchronisation with server-side pagination in a Rails app, and it explains its origin plainly. It was inspired by a Railscast, and the original author needed a similar solution in a couple of projects, so he extracted a solution into a gem. Nicolas Rodriguez is named as the current maintainer. The final goal of the gem is stated as generating a JSON content that will be given to jQuery DataTables. That is a small surface, and the README is equally clear about where customisation belongs. All the datatable customizations, header, tr, td, css classes, width, height, buttons and the rest, must take place in the javascript definition of the datatable, and the README asks you to take the time to read the DataTables option reference, because the plugin is where the flexibility lives. So the division of labour is: the server answers questions about rows, and the client decides what the table looks like. ## Server side only, with a companion gem for the client The README states the scope twice, in two slightly different ways, and both matter. It says this gem handles only the server side, and that for the client side its companion gem datatables-factory builds the HTML table and the javascript for you. That companion project lives in the same GitHub organisation, and the README links it with an anchor to a section describing how the two fit together. The consequence for a reader is that you are looking at half a stack. If you want the generator and the client side scaffolding together, you need two gems. If you already have your DataTables markup and JavaScript, and you only need the server to answer the right JSON, this gem is the piece you want. The project also points at a sample project with real world examples, hosted separately at jbox-web/ajax-datatables-rails-sample-project. For a gem whose whole job is a protocol contract, an example of the actual JSON shape and the actual table markup is worth more than another paragraph of prose. The repository tree shows a conventional gem layout with lib/, spec/, doc/, a Rakefile, a gemspec, an Appraisals file and a gemfiles/ directory for testing against multiple dependency sets. A .qlty/ directory, a .rubocop.yml and a Guardfile are also present, and there is a CLAUDE.md for agent-assisted work. ## Installing the gem and the JavaScript The gem goes into your Gemfile. ```ruby gem 'ajax-datatables-rails' ``` And then the usual install step. ```sh $ bundle install ``` The gem does not bring jQuery DataTables with it. The README assumes you have already installed it and lists four ways to do that. With importmap-rails, the Rails 7 and later default, you run `bin/importmap pin datatables.net-dt`. With jsbundling-rails you run `yarn add datatables.net-dt`. You can also add the assets manually, in vendor/assets, or use the legacy Rails webpacker gem, which has its own note in the documentation directory. That list is a good signal about the project's audience. The importmap and jsbundling entries are the current Rails defaults, while the webpacker entry is explicitly called legacy, so the gem is being maintained for a moving target rather than frozen on one asset pipeline. If you are moving from an older version of the gem, there is a migration guide in the documentation directory, and the README links it as the first thing to check before you start debugging your own code. ## Five steps from model to table The quick start assumes an index page of users from a User model, and the README recommends PostgreSQL, saying you should be using it, while noting it also works with other databases. The five steps are: generate the datatable class, build the view, customise the generated class, set up the controller action, and wire up the JavaScript. Step one is a generator. ```sh $ rails generate datatable User ``` That produces a file named user_datatable.rb in app/datatables, and you open it and customise the functions as the comments direct. Step two is the view, and the README is emphatic that you should always start from the single source of truth, which is the html view. Set up a table with a thead and a tbody, add the headers if you want them, and add no rows at all, because DataTables does that automatically. Then point the table at the JSON feed with a data attribute. ```html
ID First Name Last Name Email Brief Bio
``` The remaining three steps, the controller action and the JavaScript wiring, are the parts the README covers in its own sections, and they are where the server-side contract is closed. ## view_columns is the query you did not write The generated class is customised by declaring a column mapping in view_columns, and the mapping is what turns into the database query. ```ruby def view_columns @view_columns ||= { id: { source: "User.id" }, first_name: { source: "User.first_name", cond: :like, searchable: true, orderable: true }, last_name: { source: "User.last_name", cond: :like, nulls_last: true }, email: { source: "User.email" }, bio: { source: "User.bio" }, } end ``` The source key names the model attribute, and the other keys describe how the client is allowed to treat it. The notes are concise: by default orderable and searchable are true, and cond is :like. The cond key is where the filtering operator is chosen, and the README begins enumerating the available values, starting with :like and :start_wit..., with the rest of the list cut off in the version available here. The nulls_last option on the last_name column is the sort of detail that shows what the gem is for. Ordering by a nullable text column needs defined behaviour for the nulls, and the option names it explicitly rather than leaving it to the database, which is exactly the kind of thing that differs between the supported adapters. ## ActiveRecord, and only ActiveRecord There is one hard limitation and the README states it without hedging. AjaxDatatablesRails only supports ActiveRecord as ORM for performing database queries. The namespace AjaxDatatablesRails::ORM exists so other backends, Sequel, Mongoid and the rest, could be plugged in, but none is implemented and none is currently being worked on. The README invites people to open an issue if they would be interested in contributing to speed development. This is a much clearer statement than most projects make, and it shapes who can adopt the gem. A Rails application on ActiveRecord can use it as is. A Rails application on another ORM has to write the JSON endpoint by hand, because there is no partial support and no adapter to start from. The same honesty appears in the compatibility list. The gem is tested against Rails 7.1, 7.2, 8.0 and 8.1, and Ruby 3.1 through 4.0, with the note that Rails 8.0 and 8.1 require Ruby 3.2 or newer. Databases covered are MySQL 8, SQLite3, PostgreSQL 16 and Oracle Free 23, with the adapters sqlite, mysql2, postgres, postgis and oracle exercised in the test matrix. Two more are called out separately: trilogy and sqlserver are implemented, with type casting and NULLS LAST ordering, but are not currently exercised in CI. That is the honest form of that sentence, and it is worth taking literally, because a backend that no CI job runs is a backend nobody has proven. The protocol itself is the other compatibility anchor. The gem implements the server-side processing protocol introduced in DataTables 1.10 and works with any DataTables version speaking it, so 1.10.x and 2.x. ## Versions, and the shape of a typical upgrade The release list shows v1.3.1 on 2021-02-09, v1.4.0 on 2022-12-18 and v1.5.0 on 2024-04-08, and the last push to the repository was on 2026-07-27. The repository is not archived, so the tree continues to move while the published gems are two years old. The cadence itself is informative. A minor version every year or two, with 1.4.0 and 1.5.0 both being feature releases rather than a rapid stream of patches, is what you would expect from a gem whose compatibility surface is broad: each release tends to add a Rails version, a Ruby version or a database adapter to the matrix rather than fix a single bug. The upgrade story for a consumer is therefore predictable. A Rails 8.1 application on Ruby 3.4 should look at 1.5.0 first, because that is the newest published release, and the CI matrix in the README is the checklist of what that release claims to work with. If you are on the trilogy or sqlserver adapter, you are outside what the test matrix covers, and the project says so. The licence is MIT, with the terms in the LICENSE file at the repository root, and the gem is published on RubyGems as ajax-datatables-rails. For a library whose job is to be unremarkable infrastructure under your table markup, that is the licence you would want. ## Conclusion ajax-datatables-rails suits a Rails application with an index screen over a table large enough that rendering every row is the wrong approach, and where the team would otherwise hand write paging, sorting and filtering against the DataTables JSON protocol. It does not suit a project on a non-ActiveRecord backend, since the ORM namespace is a placeholder with nothing behind it. Verify first that your DataTables version speaks the server-side processing protocol, since that is the contract, and check the adapter list, because the trilogy and sqlserver backends are implemented but are not exercised in CI. ## FAQ ### How do I install ajax-datatables-rails? Add gem 'ajax-datatables-rails' to your Gemfile and run bundle install. The gem does not include jQuery DataTables, which the README says you must install separately, for example with bin/importmap pin datatables.net-dt or yarn add datatables.net-dt. ### How do I generate the datatable class? Run rails generate datatable User, which creates user_datatable.rb in app/datatables. You then customise the generated functions as the comments in the file direct, starting with the view_columns mapping. ### Does ajax-datatables-rails work with ORMs other than ActiveRecord? Not currently. The README says it only supports ActiveRecord, and that the AjaxDatatablesRails::ORM namespace exists so other backends such as Sequel or Mongoid could be plugged in, but none is implemented and none is currently being worked on. ### Which DataTables versions does the gem support? It implements the server-side processing protocol introduced in DataTables 1.10 and works with any DataTables version speaking that protocol, so 1.10.x and 2.x. ### What licence does ajax-datatables-rails use? The gem is MIT licensed, with the terms in the LICENSE file at the root of the repository, and it is published on RubyGems as ajax-datatables-rails. ## Sources - [Issues](https://github.com/jbox-web/ajax-datatables-rails/issues) - [jbox-web/ajax-datatables-rails on GitHub](https://github.com/jbox-web/ajax-datatables-rails) - [License: MIT](https://github.com/jbox-web/ajax-datatables-rails/blob/master/LICENSE) - [README](https://github.com/jbox-web/ajax-datatables-rails/blob/master/README.md) - [Releases](https://github.com/jbox-web/ajax-datatables-rails/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jbox-web-ajax-datatables-rails