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: [literal]#++Vaadin Icons++#. It is
automatically included in the Valo theme.

If you use other icon fonts, as described in <<themes.fonticon.custom>>,
 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 Framework includes its
own icon font, [literal]#++Vaadin Icons++#, which comes with an enumeration [classname]#VaadinIcons# with all the icons included in the font.

Most typically, you set a component icon as follows:

////
This code and rest of examples in this file are in uitest/src/main/.../VaadinIconUI.java
////
[source, Java]
----
TextField name = new TextField("Name");
name.setIcon(VaadinIcons.USER);
layout.addComponent(name);

// Button allows specifying icon resource in constructor
Button ok = new Button("OK", VaadinIcons.CHECK);
layout.addComponent(ok);
----

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.

----
.blueicon .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 " +
    VaadinIcons.HEART.getHtml() + Vaadin",
    ContentMode.HTML);
label.addStyleName("redicon");
----


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>";
}
----

[[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
VaadinIcons provided with Valo theme includes a basic character set.


----
TextField amount = new TextField("Amount (in " +
   new String(Character.toChars(
           VaadinIcons.DOLLAR.getCodepoint())) +
   ")");
amount.addStyleName("amount");
layout.addComponent(amount);
----

You need to set the font family in CSS.


----
.v-caption-amount .v-captiontext {
    font-family: Vaadin-Icons;
}
----


[[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.

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 <<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]#VaadinIcons# 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>";
    }
}
----

Then you can use it as usual:


----
TextField name = new TextField("Amount");
name.setIcon(MyFontIcon.EURO);
layout.addComponent(name);
----

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

endif::web[]