Install Preline UI with Ruby on Rails using Tailwind CSS

1. Install Preline UI

   Install preline with your preferred package manager.

   Terminal

                             
                               npm install preline
                             
                           

   Preline UI uses the Tailwind CSS Forms plugin across form components. Install it if you have not already: npm install -D @tailwindcss/forms

2. Configure CSS and JavaScript entry files

   Update your CSS and JavaScript entry files to load Preline UI and reinitialize it after Turbo page loads.

   app/assets/tailwind/application.css

                             
                               @import "tailwindcss";
   
                               @import "preline/variants.css";
                               @source "../../../node_modules/preline/dist/*.js";
   
                               /* Optional Preline UI Datepicker Plugin */
                               /* @import "preline/datepicker-styles-utility.css"; */
   
                               /* Plugins */
                               /* @plugin "@tailwindcss/forms"; */
   
                               /* Preline Themes */
                               @import "preline/theme.css";
   
                               /* Optional Preline UI Datatable Plugin: DataTables.net renders its own
                                 search/length/paging controls alongside Preline's own; hide the native
                                 ones since they can't be disabled through DataTables options alone. */
                               /*
                               .dt-layout-row:has(.dt-search),
                               .dt-layout-row:has(.dt-length),
                               .dt-layout-row:has(.dt-paging) {
                                 display: none !important;
                               }
                               */
                             
                           

   The tailwindcss-rails gem's default generator creates app/assets/tailwind/application.css as the Tailwind CSS source file, and that is the file the tailwindcss:build/tailwindcss:watch tasks compile. app/assets/stylesheets/application.css is Propshaft's separate, uncompiled manifest, so anything placed there is not run through Tailwind CSS.

   See the Theme docs to learn more about Preline Themes.

   app/javascript/application.js

                             
                               // ... other imports
                               import "preline"
   
                               // Initialize Preline components after Turbo page loads
                               document.addEventListener('turbo:load', () => {
                                 if (window.HSStaticMethods) {
                                   // Turbo Drive replaces the whole page body on every visit, so
                                   // the previous page's instances are already gone from the DOM.
                                   // Clean the registry before re-running autoInit.
                                   window.HSStaticMethods.cleanCollection();
                                   window.HSStaticMethods.autoInit();
                                 }
                               });
                             
                           

3. Configure Importmap and vendor files

   Add the Preline pin to Importmap, then copy the JavaScript file into the vendor directory.

   config/importmap.rb

                             
                               pin "preline", to: "preline.js", preload: true
                             
                           

   Terminal

                             
                               mkdir -p vendor/javascript
                               cp node_modules/preline/dist/index.mjs vendor/javascript/preline.js
                             
                           

   Rails Importmap cannot serve files directly from node_modules/. Copying the file into vendor/javascript/ keeps it available to the Rails asset pipeline. Vendor dist/index.mjs, not dist/preline.js, because the package's own exports map points the import condition at index.mjs, and it is a real ES module (it ends in export const HSStaticMethods = ...), whereas dist/preline.js is the UMD build meant for classic <script> tags.

Optional Preline UI styles

                        
                          /* Adds pointer cursor to buttons */
                          @layer base {
                            button:not(:disabled),
                            [role="button"]:not(:disabled) {
                              cursor: pointer;
                            }
                          }

                          /* Defaults hover styles on all devices */
                          @custom-variant hover (&:hover);
                        
                      

Specific guide

Continue with a focused guide for wiring Preline UI JavaScript plugins into this framework.