Trongate Icons

Trongate Icons is the icon set that ships with Trongate v2. Every icon is supplied as an individual SVG file and can be displayed using nothing more than an HTML element and a class name - no third-party library, no icon font and no JavaScript required.

Trongate Icons is completely optional and it works independently of the Trongate PHP framework. If you already have an icon library that you are happy with then you are free to carry on using it. If, on the other hand, you would prefer to remove an external dependency from your projects, Trongate Icons has you covered.

Why Trongate Icons?

• Zero dependencies: the icons are part of Trongate and they require no external CDN, no package manager and no build step.
• No icon font: each icon is an ordinary SVG file. There are no font files to load and no cryptic entity codes to memorise - just a class name.
• Colour is inherited: icons are drawn using the surrounding text colour, so an icon sitting inside a link or a button always matches that element's styling - including hover states.
• Size is inherited: icons are sized in em units, so they scale with the text that they sit beside.
• Lightweight: only the icons that are actually used on a page are downloaded. There is no giant sprite sheet and no mega stylesheet to wade through.
• Crisp at any size: because the icons are vector graphics, they stay sharp on high resolution displays.

Where The Icon Files Live

Trongate Icons consists of two things - a directory of SVG files and a stylesheet that refers to them. Both are to be found inside your project's public directory:

public/
├── css/
│   ├── trongate.css
│   └── trongate-icons.css        <-- the Trongate Icons stylesheet
└── trongate-icons/               <-- one SVG file per icon
    ├── envelope.svg
    ├── home.svg
    ├── search.svg
    └── ... (one file for every available icon)

Each icon in the set is represented by exactly one SVG file. The name of the file determines the name of the CSS class that displays it - home.svg becomes .tg-home, and so on.

Including The Stylesheet

Add a single <link> tag to the <head> section of your template:

<link rel="stylesheet" href="css/trongate-icons.css">

The complete set of Trongate stylesheets, loaded in the order that they appear inside the admin template that ships with Trongate v2, looks like this:

<link rel="stylesheet" href="css/trongate-icons.css">
<link rel="stylesheet" href="css/trongate.css">

Basic Syntax

Displaying an icon requires two class names - the base class, .tg, and a second class that identifies which icon is required. The example below produces a home icon:

<i class="tg tg-home"></i>

An <i> element is traditionally used, however any inline element will do. The following produces precisely the same icon:

<span class="tg tg-home"></span>

How The Classes Work

Every Trongate Icon is produced by combining a base class with an icon-specific class. Understanding what each one does makes the whole system easy to reason about - and easy to extend.

The Base Class

The .tg class is shared by every icon in the set. It turns an element into a single, text-sized square and paints that square using the current text colour, masked into the shape of the icon's SVG file:

.tg {
    display: inline-block;
    width: 1em;
    height: 1em;
    background-color: currentColor;
    mask-size: contain;
    mask-repeat: no-repeat;
    mask-position: center;
}

Three things about that rule are worth noting:

• The width and height of 1em means that an icon is exactly as tall as the text that surrounds it.
• background-color: currentColor means that an icon is always drawn in the colour of the text that surrounds it.
• The masking means that only the shape of the icon is visible - which is what allows a single SVG file to be displayed in any colour.

The Icon-Specific Class

The second class selects the icon. Its name always begins with tg- and it always refers to an SVG file of the same name. Here is the rule that displays the home icon:

.tg-home {
    -webkit-mask-image: url('../trongate-icons/home.svg');
    mask-image: url('../trongate-icons/home.svg');
    transform: translateY(0.03em) scale(1.2);
}

As you can see, the icon-specific rule does two jobs. First, it points at the required SVG file. Second, it applies a small transform (and, in some cases, a tiny negative margin) in order to nudge that particular shape onto the text baseline. These are optical adjustments and they are applied automatically - there is nothing extra for you to do.

Sizing Icons

Since an icon occupies 1em, its size follows the font size of whatever it sits inside. Placing an icon within a heading, for example, produces a larger icon. An icon can also be enlarged or reduced with the size classes:

<p><i class="tg tg-star"></i> Default Size</p>
<p class="sm"><i class="tg tg-star"></i> Small (.sm)</p>
<p class="xs"><i class="tg tg-star"></i> Extra Small (.xs)</p>
<p class="lg"><i class="tg tg-star"></i> Large (.lg)</p>
<p class="xl"><i class="tg tg-star"></i> Extra Large (.xl)</p>

For finer control, apply a font-size directly to the icon:

<i class="tg tg-search" style="font-size: 2.5em;"></i>

Colouring Icons

Because icons are drawn using the current text colour, changing an icon's colour is simply a matter of setting the CSS color property. This can be done on the icon itself or on any of its ancestors:

<p style="color: crimson;"><i class="tg tg-padlock"></i> Crimson padlock</p>
<p style="color: seagreen;"><i class="tg tg-eye"></i> Seagreen eye</p>
<p style="color: #3498db;"><i class="tg tg-shopping-cart"></i> Blue shopping cart</p>

The same principle applies to hover states, which makes icons a natural fit within links and buttons:

a .tg {
    color: #888;
}

a:hover .tg {
    color: #222;
}

Icons With Text

Icons are usually placed immediately before or after a label, so that they read as part of the sentence. Since each icon carries its own alignment adjustments, no extra markup is required:

<p><i class="tg tg-envelope"></i> <a href="#">Read your messages</a></p>
<p><i class="tg tg-user-circle"></i> Logged in as david</p>
<p>
    <i class="tg tg-star"></i><i class="tg tg-star"></i><i class="tg tg-star"></i><i class="tg tg-star"></i><i class="tg tg-star-half"></i>
    4.5 out of 5
</p>

Finding Available Icons

There is no lengthy reference list to consult because the icon set is the file system. Every SVG file inside public/trongate-icons/ corresponds to one icon and one class:

• the name of the file gives you the name of the class - shopping-cart.svg becomes .tg-shopping-cart;
• the same names appear inside css/trongate-icons.css, where each icon has its own rule;
• a new icon is added simply by dropping an SVG file into the directory and adding a corresponding rule to the stylesheet.

The complete set, as at version 0.1.0, is shown below. Each example is followed by the class name that produced it.

To display any icon from the set, prefix its name with tg- and place it alongside the base class. The example below displays a shopping basket:

<i class="tg tg-shopping-basket"></i>

Practical Examples

The examples below show Trongate Icons at work in situations that are common to just about every web application.

Table Row Actions

Icons make short work of the view, edit and delete actions that accompany a database record:

<a href="products/show/42" class="button alt button-round"><i class="tg tg-eye"></i></a>
<a href="products/create/42" class="button alt button-round"><i class="tg tg-pencil"></i></a>
<a href="products/delete_conf/42" class="button danger button-round"><i class="tg tg-trash"></i></a>

A Navigation Menu

Icons sit neatly within navigation lists, providing a visual cue without disturbing the layout:

<ul>
    <li><a href="dashboard"><i class="tg tg-home"></i> Dashboard</a></li>
    <li><a href="messages"><i class="tg tg-envelope"></i> Messages</a></li>
    <li><a href="orders"><i class="tg tg-shopping-cart"></i> Orders</a></li>
    <li><a href="users"><i class="tg tg-users"></i> Manage Users</a></li>
    <li><a href="logout"><i class="tg tg-sign-out"></i> Log Out</a></li>
</ul>

Form Buttons

Icons can be added to a form button by placing the icon's markup inside the button element:

<button class="success"><i class="tg tg-sign-in"></i> Log In</button>
<button class="alt"><i class="tg tg-search"></i> Search</button>

Status Indicators

Because icons inherit their colour, a colour change is all that is required to communicate a status:

<p style="color: seagreen;"><i class="tg tg-padlock"></i> Payment received</p>
<p style="color: #d68910;"><i class="tg tg-star-half"></i> Awaiting review</p>
<p style="color: crimson;"><i class="tg tg-trash"></i> Scheduled for deletion</p>

An Empty State

A large icon provides a friendly focal point when a list or a table has nothing to display:

<div class="text-center">
    <p style="font-size: 3em; color: #bbb;"><i class="tg tg-envelope-open"></i></p>
    <p><b>Your inbox is empty.</b></p>
    <p class="sm">There are no messages to display at this time.</p>
</div>

Summary

• Trongate Icons ships with Trongate v2 and requires no third-party dependencies.
• The icons live in public/trongate-icons/ and their stylesheet is public/css/trongate-icons.css.
• Display an icon with the base class .tg plus a class that names the icon - for example, <i class="tg tg-home"></i>.
• Icons inherit both colour and size from their surroundings, and they can be resized with the size classes.
• Every SVG file in the icons directory corresponds to one icon, so the directory itself is the reference.