/material_icons

A simple Rails wrapper for Google Material Icons

Primary LanguageRubyMIT LicenseMIT

Gem Version Build Status

Material Icons for Rails

Material Icons for Rails

Material Design Icons is a +2500 set of icons based on Material Design guidelines. You can check all the icons in the official site.

This gem helps you to add this fantastic icon collection to your Rails projects easily. I keep the gem updated so you always will have the latest icons in your project.

Installation

To install the gem, add this line to your Gemfile:

gem 'material_icons'

Then, execute bundle install.

CSS

In your app/assets/stylesheets/application.css.erb file you need to reference material icons CSS.

Add this line at top of application.css:

/*
*= require material_icons
*/

NOTE: Depending on the comment style of application.css, you may need to add //= require material_icons instead of the previous line. See Rails Asset Pipeline for more info.

These files provide multiple CSS classes to use in your views. Main classes are:

.material-icons, .mi

Upgrade from v2.X to 4.X

The v4.X version changed how the icon shapes are set. Before, this gem used a method_missing approach (mi.face). Due to the amount of conflicting icon shape names, in v4.X I introduced the shape method to set the icon shape:

# In v2.X
mi.face

# In v4.X
mi.shape(:face)

When upgrading to v4.X, you will need to update all the calls to the mi and material_icon helpers.

Other styles

This gem supports the new Google Material Icons styles. They are imported as a different CSS stylesheet, so you can set only the icons that are required for your project. You can set just one style or several ones.

Every CSS stylesheet includes everything you need to use that style. If you don't plan to use the regular style, feel free to include any of the next styles and remove the *= require material_icons line from your application.css.erb file.

Outlined

/*
*= require material_icons.outlined
*/

Usage in your template:

<%= material_icon.shape(:face).outlined %>
# <i class="material-icons outlined">face</i> 

Sharp

/*
*= require material_icons.sharp
*/

Usage in your template:

<%= material_icon.shape(:face).sharp %>
# <i class="material-icons sharp">face</i> 

Round

/*
*= require material_icons.round
*/

Usage in your template:

<%= material_icon.shape(:face).round %>
# <i class="material-icons round">face</i> 

Two Tone

/*
*= require material_icons.twotone
*/

Usage in your template:

<%= material_icon.shape(:face).twotone %>
# <i class="material-icons twotone">face</i> 

Helper classes

This gem includes several helper sizes. To add them to your project, add the following stylesheet:

/*
*= require material_icons.helpers
*/

After adding it, the following helpers will be available:

/* Size */
.md-18
.md-24
.md-36
.md-48

/* Color */
.md-dark
.md-light

/* Rotation */
.r90
.r180
.r270
.flip-horizontal
.flip-vertical

Don't forget to see material_icons.css.erb ;).

Views

Google Material Icons uses a feature called ligatures. We can define the icon in the text of the HTML tag. Go to Google Guide to get more info.

An example of icon is:

<i class="material-icons">face</i>
<i class="material-icons md-36">face</i>

Ruby helpers

Material Icons provide two helpers to build the HTML code of icons. The methods are material_icon and mi. These helpers use cascade style to set the icon and options. Remember you first need to add the helpers stylesheet to use these helpers.

Using same example:

<%= material_icon.shape(:face) %>
# <i class="material-icons">face</i>

<%= material_icon.shape(:face).md_36 %>
# <i class="material-icons md-36">face</i>

# You can use string too
<%= material_icon.shape('3d_rotation').md_36 %>
# <i class="material-icons md-36">3d_rotation</i>

# Rotation and custom css class
<%= mi.shape(:face).r90.css_class('my_class') %>
# <i class="material-icons r90 my_class">face</i>

# Custom css and data attributes
<%= mi.shape(:face).css_class('my_class').html(data: {id: 1}) %>
# <i data-id="1" class="material-icons my_class">face</i>

Allowed methods are:

# Rotation methods
r90
r180
r270
flip_horizontal
flip_vertical

# Size methods
md_18
md_24
md_36
md_48

# Add some classes to the icon
css_class('classes')

# Add style to the icon
style('margin-top: 5px;')

# Add some HTML attributes to an icon. This method receive a Hash
html({ data: { id: 1 } })

Remember this is a helper, you always can use HTML syntax ;).

Compatibility

Ligature feature requires a supported browser:

Browser Version
Google Chrome >= 11
Mozilla Firefox >= 3.5
Apple Safari >= 5
Microsoft IE >= 10
Opera >= 15
Apple MobileSafari >= iOS 4.2
Android Browser >= 3.0

You can find the current browser support in can I use?.

Common issues

Slim templating engine

If you are using Slim templating engine in your Rails application, use double equal == method to render icons or the content won't be marked as HTML safe. We are working on this issue, because we use content_tag and it sets the text as HTML safe (see ActionView::Helpers::TagHelper line 146).

p.text
  == material_icon.shape(:search).md_18

Reference #9

Couldn't find file 'material_icons'

couldn't find file 'material_icons' with type 'application/javascript'

This error is related with the asset compilation of Rails. To fix it, just follow these steps:

Reference #10

Tested on

Tested with GitHub Actions.

Ruby versions:

  • 2.6
  • 2.7
  • 3.0
  • 3.1

Rails versions:

  • 6.0
  • 6.1
  • 7.0

They are using Material icons for Rails :)

  • Materialup.com: a big community to share, discover and learn about Material Design.
  • Easy Bills: a free tool to manage your finances.
  • Notebook.ai: your digital notebook is here. Notebook.ai grows with your ideas and collaborates back with you.

License

Google Material Icons are under Apache License v2.0. We'd love attribution in your app's about screen, but it's not required.

Material Icons gem is released under the MIT license. Copyright Angel M Miguel