Hybrid Font Icons
Starting with the R2 2023 release, Kendo UI will no longer ship Hybrid UI components. This means that the R2 2023 will be the last release to include Kendo Hybrid in the Kendo UI package. See full announcement in Kendo jQuery blog post. The last stable version that we recommend to use for Kendo Hybrid components is R3 2022 SP1.
What's New in Kendo UI R2 2023
Important
The current Windows Phone 8 versions do not support web fonts loaded from a local CSS file when used in PhoneGap or HTML5 applications. Unfortunately, there are no known workarounds yet. Use the images for icons when targeting WP8 applications.
The Kendo UI Hybrid framework includes 38 integrated font icons, which can be used directly in a Kendo UI project intended to run on mobile devices by specifying a data-icon attribute with any of the icon names listed below, which are supported by all Button widgets and ListView items.
List of Basic Hybrid Font Icons
In addition to these icons, there are more icons available inside the font file distributed with the Kendo UI Hybrid framework. For a full list of them, check this section of the article.
Custom Font Icons
Create Custom Font Icons
Currently, to create custom font icons you have two options:
- To use a font generator service, such as Fontello, to simplify the task, or
- To manually prepare the icon, SVG, and fonts.
Use Font Generator Service
Using Fontello is pretty straightforward—pick the icons, choose the Unicode characters for them, type a font name, and click Download to get a .zip file with the needed for mobile TTF and WOFF font formats, which can be directly used for icons. From the other files in there, EOT is not needed as it targets only Internet Explorer 6 to 8 versions and the SVG font can be used to further the modification.
Create Icons Manually
The manual approach is considerably more difficult. First, create the desired icons using a vector editing software such as Inkscape or Adobe Illustrator. Export them to the SVG format. Consult these articles about SVG font creation using Inkscape. Import the SVG icons in Inkscape and create the SVG font icon by icon, assigning them to separate characters. After creating the SVG font, convert it to TTF/WOFF formats, using the Online Font Converter or other similar service.
The example below demonstrates how to load the two fonts (TTF/WOFF) with @font-face.
<style>
@font-face {
font-family: "MyCustomFont";
src: url("images/MyCustomFont.woff") format("woff"),
url("images/MyCustomFont.ttf") format("truetype");
}
</style>
The example below demonstrates how to override the Kendo UI font for all icons. Note that, alternatively, separate classes can be used to override them one by one.
<style>
.km-icon:after,
.km-icon:before
{
font: 1em/1em "MyCustomFont";
}
</style>
<div data-role="tabstrip">
<a href="#index" data-icon="favorites">Home</a>
</div>
The example below demonstrates how to specify the character corresponding to every custom icon.
<style>
.km-mycustomicon:after,
.km-mycustomicon:before
{
content: "\E03a";
}
</style>
<div data-role="tabstrip">
<a href="#index" data-icon="mycustomicon">Home</a>
</div>
In the example, mycustomicon is the icon name set in the data-icon attribute and \E03a is the Unicode character code of the icon.
Serving Font Files
As of Kendo UI Q3 2012, the hybrid framework employs an icon font for its icon rendering. To be able to render it in most of the supported mobile and desktop browsers, two font formats included in the Kendo UI distribution exist—TTF and WOFF. Most web servers do not support serving these fonts with a specific mime type. Since currently there is no standardized mime type for fonts, you only need to serve them both with mime type application/octet-stream or you can come up with any valid mime type such as application/x-font-ttf and application/x-font-woff, for example.
Configure IIS
The two mime types can be specified either through the IIS management console (inetmgr) or in the site Web.config.
The example below demonstrates how to configure IIS Web.config.
<?xml version="1.0"?>
<configuration>
...
<system.webServer>
...
<staticContent>
<remove fileExtension=".ttf" />
<mimeMap fileExtension=".ttf" mimeType="application/octet-stream" />
<remove fileExtension=".woff" />
<mimeMap fileExtension=".woff" mimeType="application/octet-stream" />
</staticContent>
</system.webServer>
</configuration>
Removing the mime type first avoids clashes if the mime types for these files are already defined. Note that IIS throws exception if they are. These can be removed if not needed.
Configure Apache
Apache configuration in some distributions includes mime-types application/x-font-ttf and application/x-font-woff by default. If these mime types are not listed, they can be added easily.
Configure in .htaccess
The example below demonstrates how to configure Apache in .htaccess.
AddType application/x-font-ttf .ttf
AddType application/x-font-woff .woff
Configure the mime.types File
The example below demonstrates how to configure the Apache mime.types file.
application/x-font-ttf .ttf
application/x-font-woff .woff
Configure Nginx
For Nginx the configuration is similar.
Configure the mime.types File
The example below demonstrates how to configure the Nginx mime.types file.
application/x-font-ttf .ttf
application/x-font-woff .woff
Configuration of CORS Headers
Handle CORS Headers
Since fonts are usually copyrighted, most browsers do not allow using them across different domains. If serving multiple domains from one font location is needed, the fonts should be served with an Access-Control-Allow-Origin header. This header also supports using * instead of the domain name list, and while using it for normal text fonts is not advisable, it can be freely used for our icon font if the icons are living in a Kendo UI hybrid application.
Configure IIS
The example demonstrates how to configure IIS by placing a web.config in the font folder and adding the code below to it.
<httpProtocol>
<customHeaders>
<add name="Access-Control-Allow-Origin" value="*" />
</customHeaders>
</httpProtocol>
Configure Apache
The example demonstrates how to configure Apache.
<FilesMatch "\.(ttf|woff)$">
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</FilesMatch>
Configure Nginx
The example demonstrates how to configure Nginx.
location / {
...
if ($filename ~* \.(ttf|woff)$){
add_header Access-Control-Allow-Origin *;
}
}
Usage of Custom Icons
Custom Icons with Background-Image
To use any image for an icon in the Kendo UI hybrid framework, raise the specificity of the background-image style to at least 40 to override the defaults. Use background-size to resize the image accordingly.
The example below demonstrates how to define custom background-image icon.
<style>
.km-root .km-pane .km-view .km-custom
{
background-image: url("custom.jpg");
-webkit-background-clip: border-box;
}
</style>
<div data-role="tabstrip">
<a href="#index" data-icon="custom">Home</a>
</div>
Custom Icons with WebKit Masks
To use colorizable icon masks, specify the icon image as a box mask—either as dataURI or as a separate image. The image should be PNG8 or PNG24 with alpha channel. Note that PNG8+Alpha is supported only by few graphic editors, so you'd better stick to PNG24 if not sure. The image color is not important—it is going to be used as a mask only—the alpha transparency clips the colorized content.
Important
- WebKit masks have numerous bugs across most platforms, so consider using them only if necessary.
- In Android and MeeGo WebKit masks are unreliable—they can be turned into colorized rectangles by a simple CSS transformation in the wrong place. In BBOS 7.0 WebKit masks are completely broken—though they work in BBOS 6.0 and 7.1.
Define Custom WebKit Mask for Icons
The example below demonstrates how to define a custom WebKit mask for an icon.
<style>
.km-custom {
-webkit-mask-box-image: url("foo.png");
}
</style>
<div data-role="tabstrip">
<a href="#index" data-icon="custom">Home</a>
</div>
Custom WebKit Masks after Kendo UI Q3 2012
Important
WebKit masks are now deprecated for Android mobile applications, where
background: url()should be used instead. WebKit masks can still be used in iOS applications.
In Kendo UIQ3 2012 WebKit mask icons were deprecated due to numerous issues with them and the Kendo UI hybrid framework introduced font icons. This change requires the usage of additional styling to enable the WebKit masks as icons.
This example demonstrates how to define custom icon after Kendo UI Q3 2012. Note that the the code from below is going to disable all font icons.
<style>
.km-root .km-pane .km-view .km-icon {
background-size: 100% 100%;
-webkit-background-clip: border-box;
background-color: currentcolor;
}
.km-custom {
-webkit-mask-box-image: url("foo.png");
background-color: red;
}
</style>
<div data-role="tabstrip">
<a href="#index" data-icon="custom">Home</a>
</div>
Restyle Only Custom Icons
If you want to add only one or two custom icons, specify them with their respective classes—.km- + data-icon name. The example below demonstrates how to restyle only the custom icons.
<style>
.km-root .km-pane .km-view .km-question {
background-size: 100% 100%;
-webkit-background-clip: border-box;
background-color: currentcolor;
}
.km-question {
-webkit-mask-box-image: url("foo.png");
background-color: red;
}
</style>
<div data-role="tabstrip">
<a href="#index" data-icon="question">Home</a>
</div>
Hide All Hybrid Font Icons
When custom icons are used and their names are the same as the integrated Kendo UI hybrid icon names, make sure that the font icons are not rendered. The example below demonstrates how to hide all Kendo UI hybrid font icons.
<style>
.km-root .km-pane .km-view .km-icon:after,
.km-root .km-pane .km-view .km-icon:before
{
visibility: hidden;
}
</style>
<div data-role="tabstrip">
<a href="#index" data-icon="custom">Home</a>
</div>
Hide Specific Hybrid Font Icons
Again, if only several icons should be overridden, specify them with their classes instead. The example below demonstrates how to hide only one Kendo UI hybrid font icon.
<style>
.km-root .km-pane .km-view .km-favorites:after,
.km-root .km-pane .km-view .km-favorites:before
{
visibility: hidden;
}
</style>
<div data-role="tabstrip">
<a href="#index" data-icon="favorites">Home</a>
</div>
Custom Icons on Windows Phone 8
Windows Phone 8.0 has some severe issues that may affect your icons usage. First of all, masks are not supported in any way—Firefox allows SVG mask usage, WebKit/Blink have image masks, although broken in Android. If you plan to have only a web application that runs in the browser, you can go for font icons as they look better across different resolutions and can be colorized. The default Kendo UI hybrid icons work as any icon font such as Font Awesome. Learn more about using font icons and Font Awesome from this blog post.
However, if you plan to create a hybrid application with PhoneGap or HTML5 template in WP8 SDK, font icons do not work there—the WebView does not load them at all. Kendo UI provides image replacements for its default icons, but if you want custom ones, you are left out with only normal images/backgrounds and you need to provide one for normal and another one for the selected state, if they differ. You should also think about the dark and light background themes in WP8, as the Kendo UI hybrid framework automatically supports them in Cordova.
The example below demonstrates how the WP8 application icon backgrounds are defined in the Kendo UI hybrid framework.
<style>
.km-on-wp.km-app .km-icon:after,
.km-on-wp.km-app .km-filter-wrap:before,
.km-on-wp.km-app .km-state-active .km-icon:after
{
background-image: url("images/wp8_icons.png");
}
.km-wp-light.km-app .km-icon:after,
.km-wp-light.km-app .km-filter-wrap:before
{
background-image: url("images/wp8_inverseicons.png");
}
.km-on-wp.km-app .km-action:after
{
background-position-x: 20%;
}
.km-on-wp.km-app .km-add:after
{
background-position-x: 22%;
}
</style>
The sprite is laid out horizontally and background-size and background-position-x are used to specify the icon offsets. This is done to allow the icon to be resized with its container size. You do not need your icons to have circles around them, as they are defined in CSS just for the TabStrip.
List of Additional Hybrid Font Icons
The icon font shipped with the Kendo UI hybrid distribution contains much more icons than the 34 defined ones—about ten times more than that. The reason for this is that the framework aims at keeping its CSS small. To use them, choose an icon from the list below and add a definition for it in your CSS using its Unicode character code. Make sure you have a km- prefix.
<style>
.km-arrow-e:after,
.km-arrow-e:before
{
content: "\e000";
}
</style>
<div data-role="tabstrip">
<a href="#index" data-icon="arrow-e">Home</a>
</div>
Now you are able to specify it as a data-icon="arrow-e" in your application.
Keep in mind that icons with Unicode codes from \e0ca to \e0f0 are the original Kendo UI hybrid icons listed at the beginning of this article. Also, the ones starting from \e200 are already defined and in use, but only in the iOS7 platform theme and are available as of Kendo UI Q2 2013 SP.