The shoelace-rails
gem adds useful helper methods for Shoelace.style, the design system.
- For Shoelace version >= 2.0.0-beta.88, use the gem version
0.4.0
or above. - For Shoelace version <= 2.0.0-beta.87, use the gem version
0.3.0
.
Add this line to your application's Gemfile:
gem 'shoelace-rails'
And then execute:
$ bundle install
Additionally, you need to add the following npm packages:
$ yarn add @shoelace-style/shoelace
Add the following lines to the app/assets/stylesheets/application.css
if you need the sprockets gem:
/*
*= require @shoelace-style/shoelace/dist/themes/light.css
*= require @shoelace-style/shoelace/dist/themes/dark.css
*/
Add the following lines to the app/packs/entrypoints/application.js
if you prefer the webpack and CSS loader:
import "@shoelace-style/shoelace/dist/themes/light.css"
import "@shoelace-style/shoelace/dist/themes/dark.css" // Optional dark mode
In this README, it is assumed that you are using a JS bundler such as webpack
or esbuild
. In order to define all
the custome elements, import the shoelace dependency in the entrypoint file:
import "@shoelace-style/shoelace"
That's it!
Shoelace icons are automatically set up to load properly, so you don't need to add any extra code. More specifically,
- In development, the icons are served by the
ActionDispatch::Static
middleware, directly from thenode_modules/@shoelace-style/shoelace/dist/assets/icons
directory. - In production, the icon files are automatically copied into the
public/assets
directory as part of theassets:precompile
rake task.
As explained above, this gem provides drop-in replacements to Rails view helpers.
The sl_form_with
or sl_form_for
method could be used to generate a form with the Shoelace components:
<%= sl_form_for @user do |form| %>
<% # Text input: https://shoelace.style/components/input %>
<%= form.text_field :name %>
<%= form.password_field :password, placeholder: "Password Toggle", 'toggle-password': true %>
<% # Radio buttons: https://shoelace.style/components/color-picker %>
<%= form.color_field :color %>
<% # Radio buttons: https://shoelace.style/components/radio %>
<%= form.collection_radio_buttons :status, { id_1: "Option 1", id_2: "Option 2", id_3: "Option 3" }, :first, :last %>
<% # Select: https://shoelace.style/components/select %>
<%= form.collection_select :tag, { id_1: "Option 1", id_2: "Option 2", id_3: "Option 3" }, :first, :last, {}, { placeholder: "Select one" } %>
<%= form.submit %>
<% end %>
And this code will produce:
<form class="new_user" id="new_user" data-remote="true" action="/" accept-charset="UTF-8" method="post">
<sl-input label="Name" type="text" name="user[name]" id="user_name"></sl-input>
<sl-input label="Password" type="password" name="user[password]" id="user_password"></sl-input>
<sl-color-picker value="#ffffff" name="user[color]" id="user_color"></sl-color-picker>
<sl-radio-group no-fieldset="true">
<sl-radio value="id_1" name="user[status]" id="user_status_id_1">Option 1</sl-radio>
<sl-radio value="id_2" name="user[status]" id="user_status_id_2">Option 2</sl-radio>
<sl-radio value="id_3" name="user[status]" id="user_status_id_3">Option 3</sl-radio>
</sl-radio-group>
<sl-select placeholder="Select one" name="user[tag]" id="user_tag">
<sl-menu-item value="id_1">Option 1</sl-menu-item>
<sl-menu-item value="id_2">Option 2</sl-menu-item>
<sl-menu-item value="id_3">Option 3</sl-menu-item>
</sl-select>
<sl-button submit="true" type="primary" data-disable-with="Create User">Create User</sl-button>
</form>
TDB
Sometimes you want to use the Shoelace FormBuilder with other gems, such as ransack.
In this case, you can not use the sl_form_for
or sl_form_with
methods in tandem with ransack
, but you can use
the Shoelace::FormBuilder
with e.g. the search_form_for
method:
<%= search_form_for @q, builder: Shoelace::FormBuilder do |form| %>
...
<% end %>
The @sl_avatar_tag
method behaves just like the image_tag
method.
<%= sl_avatar_tag "/path/to/image.jpg" %>
Will produce:
<sl-avatar image="/path/to/image.jpg"></sl-avatar>
The sl_button_to
method behaves just like the link_to
method. Note that this is slightly different from the
built-in button_to
method.
Without a block:
<%= sl_button_to "Next Page", "/components?page=2" %>
<sl-button href="/components?page=2">
Next Page
</sl-button>
With a block:
<%= sl_button_to "/components?page=2" do %>
Next Page
<% end %>
<sl-button href="/components?page=2">
Next Page
</sl-button>
The sl_icon_tag
method takes the name
attribute value as the first argument:
<%= sl_icon_tag "apple" %>
<sl-icon name="apple"></sl-icon>
- Run
bundle install
- Make a change and add test coverage
- Run
bundle rails test
- Make a commit and push it to GitHub
- Send us a pull request
Bug reports and pull requests are welcome on GitHub at https://github.com/yuki24/shoelace-rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Shoelace::Rails project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.