---json
{
    "description": "An icon component that makes it easy to add icon to your pages",
    "page_id": "vzs3sp5vzvfw0wnaz1dnc",
    "title": "ComboStrap - Icon Component"
}
---
====== ComboStrap UI - Icon Component ======

===== About =====
''icon'' is a [[docs:component|component]] that permits to add easily an [[docs:content:svg|svg]] icon such as this one: <icon name="bs:emoji-wink" color="steelblue" width="22px"/> :
  * from an [[#library|icon library]]
  * or from your media library as a [[#how_to_show_any_icons|SVG media file]]



===== Example =====
==== Material Design Icon ====


Example with the [[https://materialdesignicons.com/icon/arrow-down-circle|arrow-down-circle]] 
  * The default [[:docs:theme:branding-colors|secondary color]] is used by default
<webcode name="Material-Design">
<code dw>
<icon name="arrow-down-circle" />
</code>
</webcode>
  * The default [[:docs:theme:branding-colors|primary color]] is used for icon bigger than 36
<webcode name="Material-Design">
<code dw>
<icon name="arrow-down-circle" width="60"/>
</code>
</webcode>


==== Bootstrap ====

Example with the [[https://icons.getbootstrap.com/icons/arrow-down-circle-fill/|arrow-down-circle-fill]] and a ''blue'' [[docs:styling:color|color]]
<webcode name="Boostrap">
<code dw>
<icon name="bootstrap:arrow-down-circle-fill" color="blue" width="48px" />
</code>
</webcode>

==== Feather ====
Example with a [[https://feathericons.com/?query=box|''box'' icon]] and a [[docs:styling:color|color]]
<webcode name="Feather">
<code dw>
<icon name="fe:box" color="blue" width="48px" height="48px" />
</code>
</webcode>


==== Zoom out - Illustrative Icon ====

In case of an illustrative icon used for instance in a [[docs:block:card|card]] or as [[docs:content:page-image|page image]], the icon may be zoomed out (by default, the value is 4)

Example of icon zoomed out by a factor of 3.
<webcode name="Feather">
<code dw>
<icon name="fe:box" color="skyblue" width="200" height="200" zoom=-3 border-color="skyblue" />
</code>
</webcode>


==== Multiple Colors ====


We support multiple colors icons. 
  * For instance, with the [[https://icon-sets.iconify.design/flat-color-icons/smartphone-tablet/|flat-color-icons:smartphone-tablet]] icon
<webcode>
<code dw>
<icon name="flat-color-icons:smartphone-tablet" width="100" />
</code>
</webcode>
  * If a color is set, we change the first color found.
<webcode>
<code dw>
<icon name="flat-color-icons:smartphone-tablet" color="skyblue" width="200" zoom=-3 border-color="skyblue" />
</code>
</webcode>
===== Syntax =====
An icon can be seen as a character and is therefore a component that can be used in a [[docs:content:content|line]].

The syntax is:
<code dw>
<icon name="[library:]icon-name" color="color" width="width" zoom="factor"/>
</code>
where:
  * ''name'' is the [[https://icon-sets.iconify.design/|full qualified Iconify search engine name]] where:
      * ''library'' is the optional name of a [[#library|supported icon library]] (if not set, the [[#default library|default]] is used)
      * ''icon-name'' is the name of the icon 
  * ''color'' is the [[docs:styling:color|color value]]. By default:
      * the [[:docs:theme:branding-colors|secondary color]] (if the icon width is less than 36 px)
      * the [[:docs:theme:branding-colors||primary color]] otherwise.
  * ''width'' is the [[docs:styling:dimension|width value]]
  * ''zoom'' is a zoom factor (zoom in when the factor is positive, zoom out otherwise). A zoom is performed after a [[docs:content:image#crop|crop]].


===== How to show an icon ? =====

To show a icon:
  * Go to the [[https://icon-sets.iconify.design/|Iconify search engine]],
  * Search an icon
  * Verify that we support the [[#library]] (if the library is not supported, see the [[#how_to_show_any_icons|next paragraph]])
  * Copy the Iconify full qualified name
  * And use it with the icon syntax.

===== How to show any icons ?  =====

If the [[#library]] is not yet supported, you can also easily embedded it.

You just need to follow this steps:
  * go to your icon repository 
  * download your icon
  * upload it to your [[doku>images|media library]] (preferably under the directory ''combostrap:icons'')
  * use it:
      * with the [[#syntax|icon syntax]] (if saved under the directory ''combostrap:icons'')
      * with the [[docs:content:svg|svg]] syntax with a value of ''icon'' for the ''type'' attribute


Example with [[https://fonts.google.com/icons|Google icon]] and the ''favorite'' icon saved in the media library in the namespace ''combostrap:icons:google''
  * with the [[docs:content:svg|svg syntax]]
<webcode name="SvgIconSyntax" frameborder=0  >
<code dw>
{{:combostrap:icons:google:favorite_black_24dp.svg?36&type=icon&color=steelblue|}}
</code>
</webcode>
  * with the [[#syntax|icon syntax]] (if you saved it under the directory ''combostrap:icons'')
<webcode name="IconGoogleSyntax" frameborder=0  >
<code dw>
<icon name="google:favorite_black_24dp" width="36" color="purple"/>
</code>
</webcode>




===== Properties =====

==== Color ====
In the color attribute, you can set a [[docs:styling:color#value|color value]].

ComboStrap detects automatically if the icon is a ''solid'' or ''outline'' one and sets the color accordingly.


Example with the [[https://icons.getbootstrap.com/|bootstrap alarm clock]]

<grid>
  <box>
The ''outline'' icon
<webcode name="outline" frameborder=0 >
<code dw>
<icon name="bs:alarm" color="pink" />
</code>
</webcode>
  </box>
  <box>
Versus the ''solid'' (ie''fill'')  icon
<webcode name="Solid">
<code dw>
<icon name="bs:alarm-fill" color="pink" />
</code>
</webcode>
  </box>
</grid>

==== Sizing: Width and Height ====
The ''width'' and ''height'' attributes have the same value and takes the default value of ''24px'' but you can overwrite it.
<webcode name="Sizing" frameborder="0" >
<code dw>
<icon name="logo.svg" width="96px" />
</code>
</webcode>
==== Styling and Native Attribute ====


The ''icon'' component supports also :
  * all SVG attributes ([[https://developer.mozilla.org/en-US/docs/Web/SVG/Element/svg|svg attributes]])
  * and [[docs:styling:styling|styling attribute]]


Example:
  * with a [[docs:animation:hover|hover animation]]
<webcode name="Solid">
<code dw>
<icon name="bs:alarm-fill" color="pink" onHover="grow" width="36"/>
</code>
</webcode>

===== Library =====

The icon component supports the below libraries natively.

The ''acronym'' should be used as library name. It follows the [[https://icon-sets.iconify.design/|acronyn found in the iconify search engine]]


^ Name ^ Acronym ^ WebSite^
| ''ant-design'' | ''ant-design'' | [[https://ant.design/components/icon/|Ant design]] |
| ''akar-icons''  | ''akar-icons'' | [[https://akaricons.com/|akaricons]] (MIT) |
| ''arcticons'' | ''arcticons'' | [[https://arcticons.com/]] (CC BY-SA 4.0) |
| ''bootstrap'' | ''bi'' | [[https://icons.getbootstrap.com/|Bootstrap icon]] |
| ''boxicons'' | ''bx'' | [[https://boxicons.com/|Boxicons]] (CC BY 4.0) |
| ''carbon'' | ''carbon'' | [[https://www.carbondesignsystem.com/guidelines/icons/library/|Carbon (IBM)]] |
| ''clarity'' | ''clarity'' | [[https://clarity.design/foundation/icons/|Clarity icon (essential)]] |
| ''codicon'' | ''codicon'' | [[https://microsoft.github.io/vscode-codicons/|Microsoft Code Icon]] |
| ''core ui brand'' | ''cib'' | [[https://coreui.io/icons/|Core Ui Icons]] |
| ''dashicons'' | ''dashicons'' | [[https://developer.wordpress.org/resource/dashicons/|Wordpress dashicons]] | 
| ''elegant theme'' | ''et'' | [[https://github.com/pprince/etlinefont-bower|Elegant Themes]] |
| ''eva'' | ''eva'' | [[https://akveo.github.io/eva-icons/#/|Eva Icons]] |
| ''fad'' | ''fad'' | [[https://github.com/fefanto/fontaudio/|Fad (Font Audio Icons)]] |
| ''flat color button'' | ''flat-color-icons'' | [[https://icons8.com/icons/color|Icons8]] (MIT) |
| ''font awesome brands'' | ''fa-brands'' | [[https://fontawesome.com/|Font Awesome]] (CC BY 4.0) |
| ''font awesome regular'' | ''fa-regular'' | [[https://fontawesome.com/|Font Awesome]] (CC BY 4.0) |
| ''font awesome solid'' | ''fa-solid'' | [[https://fontawesome.com/|Font Awesome]] (CC BY 4.0) |
| ''feather'' | ''fe'' | [[https://feathericons.com/|Feather]] |
| ''healthicons'' | ''healthicons'' | [[https://healthicons.org/|Healthicons (MIT)]] |
| ''icomoon'' | ''icomoon-free'' | [[https://icomoon.io/|Icomoon]] | 
| ''iconoir'' | ''iconoir'' | [[https://iconoir.com/|Iconoir]] | 
| ''iconscout'' | ''uit'' | [[https://iconscout.com/unicons/explore/line|Iconscout (Line only)]] |
| ''line awesome'' | ''la'' | [[https://icons8.com/line-awesome|Line Awesome]] (MIT) | 
| ''logos'' | ''logos'' | [[https://svgporn.com/|SvgPorn]] |
| ''material-design'' | ''mdi'' | [[https://materialdesignicons.com/|Material design icon]] |
| ''octicon'' | ''octicon'' | [[https://primer.style/octicons/|Github Octicons]] |
| ''phosphor icon'' | ''ph'' | [[https://phosphoricons.com/|Phosphor Icons]] | 
| ''simple line'' | ''simple-line-icons'' | [[https://thesabbir.github.io/simple-line-icons|Simple Line Icons]] |
| ''si glyph'' | ''si-glyph'' | [[https://glyph.smarticons.co/|Si Glyph by Smarticons]] (CC BY SA 4.0) |
| ''twemoji'' | ''twemoji'' | [[https://twemoji.twitter.com/|Twitter Emoji]] |
| ''vaadin'' | ''vaadin'' | [[https://vaadin.com/icons|Vaadin Icons]] |
| ''vscode'' | ''vscode-icons'' | [[https://marketplace.visualstudio.com/items?itemName=vscode-icons-team.vscode-icons|VsCode Icons]] (MIT) |


The default library is ''material-design'' but you can [[#configuration|change this configuration]].

<note >
=== Other library ===

You can also download an icon from your preferred icon library and use it directly.

[[#other_library_such_as_google_icon|How to use an other icon library such as Google Icon]].
</note>




===== Configuration =====
==== Icons namespace ====
When the ''icon'' does not exist, the component downloads the icons in the namespace set in the ''icons_namespace'' configuration.

The default value is '':combostrap:icons''

<note type="tip">
On the server, the namespace is a location from the media directory: ''DOKUWIKI_HOME/data/media/''
{{docs:block:icon_default_location_combostrap.png|}}
</note>

==== Default Library ====

You can change the default library with the ''defaultIconLibrary'' [[docs:app:configuration|configuration]].

At installation time, the default library is [[#material design|material design]].

===== Icon Vs Svg =====

An ''icon'' is just a [[docs:content:svg|svg]] that is seen as a character.


ComboStrap sets the following properties on a icon by default:
  * ''width'' and ''height'' have the same value (default to ''24px'')
  * [[docs:styling:color|color]]: ''currentColor'' by default
  * not responsive (no ''preserveAspectRatio'' and no max length CSS properties)
  * no [[docs:content:image#align|alignment]] (ie no left, center or right)


<note tip>
As an icon is just a svg, you can also use the [[docs:content:svg|svg syntax]] directly against a custom svg to embed it as an icon.

Example:
<code dw>
{{:custom-icon.svg?16&type=icon|}}
</code>
</note>



===== Support =====


==== Prerequisite ====

This component uses the [[support:requirement|DOM module]]. This module is enabled by default on all hosting platform. It should be then no problem for most of your installation.


==== What to do if my icon does not render correctly ? ====


If your icon comes from a [[#library|supported library]] and does not render correctly, [[:support|contact us or create an issue]]


Otherwise, check this [[support:preserve|answer]]





==== Why downloading the image and not using a library ====

We are not using a library and have decided to download the [[docs:content:svg|svg]] file for the following reasons:
  * the icon can then be used as
      * [[docs:page:image|illustrative page image]]
      * [[docs:social:share|Share Icon]]
  * even if the library does not exist anymore, your page will still show the icon.