Rails helpers for https://shoelace.style, the design system.
MIT License
The shoelace-rails
gem adds useful helper methods for Shoelace.style, the design system.
0.4.0
or above.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,
ActionDispatch::Static
middleware, directly from thenode_modules/@shoelace-style/shoelace/dist/assets/icons
directory.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>
sl-select
component with multiple
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 %>
#sl_avatar_tag
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>
#sl_button_to
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>
#sl_icon_tag
The sl_icon_tag
method takes the name
attribute value as the first argument:
<%= sl_icon_tag "apple" %>
<sl-icon name="apple"></sl-icon>
bundle install
bundle rails test
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.