vaadin-framework/documentation/themes/themes-fonticon.asciidoc

---
title: Font Icons
order: 8
layout: page
---

[[themes.fonticon]]
= Font Icons

Font icons are icons included in a font. Fonts have many advantages over bitmap
images. Browsers are usually faster in rendering fonts than loading image files.
Web fonts are vector graphics, so they are scalable. As font icons are text
characters, you can define their color in CSS by the regular foreground color
property.

[[themes.fonticon.enabling]]
== Loading Icon Fonts

Vaadin currently comes with one custom icon font: FontAwesome. It is
automatically enabled in the Valo theme. For other themes, you need to include
it with the following line in your project theme, after importing the base
theme:

----
@include fonticons;
----

If you use other icon fonts, as described in <<themes.fonticon.custom>>, and the
font is not loaded by a base theme, you need to load it with a
`font` mixin in Sass, as described in
<<themes-fonts#themes.fonts.loading,"Loading Local Fonts">>.


[[themes.fonticon.using]]
== Basic Use

Font icons are resources of type [classname]#FontIcon#, which implements the
[interfacename]#Resource# interface. You can use these special resources for
component icons and such, but not as embedded images, for example.

Each icon has a Unicode codepoint, by which you can use it. Vaadin includes an
awesome icon font, [literal]#++FontAwesome++#, which comes with an enumeration
of all the icons included in the font.

Most typically, you set a component icon as follows:

[source, Java]
----
TextField name = new TextField("Name");
name.setIcon(FontAwesome.USER);
layout.addComponent(name);

// Button allows specifying icon resource in constructor
Button ok = new Button("OK", FontAwesome.CHECK);
layout.addComponent(ok);
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.basic[on-line example, window="_blank"].

The result is illustrated in <<figure.themes.fonticon.using>>, with the color
styling described next.

[[figure.themes.fonticon.using]]
.Basic Use of Font Icons
image::img/fonticons-basic.png[]

[[themes.fonticon.using.css]]
=== Styling the Icons

As font icons are regular text, you can specify their color with the
[literal]#++color++# attribute in CSS to specify the foreground text color. All
HTML elements that display icons in Vaadin have the [literal]#++v-icon++# style
name.

----
.v-icon {
    color: blue;
}
----

If you use the font icon resources in other ways, such as in an
[classname]#Image# component, the style name will be different.


[[themes.fonticon.html]]
== Using Font icons in HTML

You can use font icons in HTML code, such as in a [classname]#Label#, by
generating the HTML to display the icon with the [methodname]#getHtml()# method.

[source, Java]
----
Label label = new Label("I " +
    FontAwesome.HEART.getHtml() + " Vaadin",
    ContentMode.HTML);
label.addStyleName("redicon");
layout.addComponent(label);
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.html[on-line example, window="_blank"].

The HTML code has the [stylename]#v-icon# style, which you can modify in CSS:

[source, css]
----
.redicon .v-icon {
    color: red;
}
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.html[on-line example, window="_blank"].

The result is illustrated in <<figure.themes.fonticon-html.label>>, with the color
styling described next.

// The ID may not end in ".html"
[[figure.themes.fonticon-html.label]]
.Using Font Icons in Label
image::img/fonticons-html.png[]

You could have set the font color in the label's HTML code as well, or for all
icons in the UI.

You can easily use font icons in HTML code in other ways as well. You just need
to use the correct font family and then use the hex-formatted Unicode codepoint
for the icon. See for example the implementation of the [methodname]#getHtml()#
method in [classname]#FontAwesome#:

----
@Override
public String getHtml() {
    return "<span class=\"v-icon\" style=\"font-family: " +
           getFontFamily() + ";\">&#x" +
           Integer.toHexString(codepoint) + ";</span>";
}
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.html[on-line example, window="_blank"].


[[themes.fonticon.anywhere]]
== Using Font Icons in Other Text

You can include a font icon in any text by its Unicode codepoint, which you can
get with the [methodname]#getCodePoint()# method. In such case, however, you
need to use the same font for other text in the same string as well. The
FontAwesome provided in Vaadin includes a basic character set.


----
TextField amount = new TextField("Amount (in " +
   new String(Character.toChars(
           FontAwesome.BTC.getCodepoint())) +
   ")");
amount.addStyleName("awesomecaption");
layout.addComponent(amount);
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.intext[on-line example, window="_blank"].

You need to set the font family in CSS.


----
.v-caption-awesomecaption .v-captiontext {
    font-family: FontAwesome;
}
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.intext[on-line example, window="_blank"].


[[themes.fonticon.custom]]
== Custom Font Icons

You can easily use glyphs in existing fonts as icons, or create your own.

[[themes.fonticon.custom.creating]]
=== Creating New Icon Fonts With IcoMoon

You are free to use any of the many ways to create icons and embed them into
fonts. Here, we give basic instructions for using the
link:http://icomoon.io/app/[IcoMoon] service, where you can pick icons from a
large library of well-designed icons.

Font Awesome is included in IcoMoon's selection of icon libraries. Note that the
codepoints of the icons are not fixed, so the [classname]#FontAwesome# enum is
not compatible with such custom icon fonts.

After you have selected the icons that you want in your font, you can download
them in a ZIP package. The package contains the icons in multiple formats,
including WOFF, TTF, EOT, and SVG. Not all browsers support any one of them, so
all are needed to support all the common browsers. Extract the [filename]#fonts#
folder from the package to under your theme.

See <<dummy/../../../framework/themes/themes-fonts#themes.fonts.loading,"Loading
Local Fonts">> for instructions for loading a custom font.


ifdef::web[]
[[themes.fonticon.custom.implementing]]
=== Implementing FontIcon

You can define a font icon for any font available in the browser by implementing
the [interfacename]#FontIcon# interface. The normal pattern for implementing it
is to implement an enumeration for all the symbols available in the font. See
the implementation of [classname]#FontAwesome# for more details.

You need a FontIcon API for the icons. In the following, we define a font icon
using a normal sans-serif font built-in in the browser.


----
// Font icon definition with a single symbol
public enum MyFontIcon implements FontIcon {
    EURO(0x20AC);

    private int codepoint;

    MyFontIcon(int codepoint) {
        this.codepoint = codepoint;
    }

    @Override
    public String getMIMEType() {
        throw new UnsupportedOperationException(
            FontIcon.class.getSimpleName()
            + " should not be used where a MIME type is needed.");
    }

    @Override
    public String getFontFamily() {
        return "sans-serif";
    }

    @Override
    public int getCodepoint() {
        return codepoint;
    }

    @Override
    public String getHtml() {
        return "<span class=\"v-icon\" style=\"font-family: " +
                getFontFamily() + ";\">&#x" +
                Integer.toHexString(codepoint) + ";</span>";
    }
}
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.custom[on-line example, window="_blank"].

Then you can use it as usual:


----
TextField name = new TextField("Amount");
name.setIcon(MyFontIcon.EURO);
layout.addComponent(name);
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.custom[on-line example, window="_blank"].

You could make the implementation a class as well, instead of an enumeration, to
allow other ways to specify the icons.

endif::web[]