Skip to content
Navigation

Primary

Icon

An icon helps readers recognise an action or a state quickly. Docara icons are Google’s Material Symbols set: 3926 icons in three families. The set ships with Docara, so the site needs no access to Google Fonts.

Example

settings

Markup

Markdown
:icon[search]{label="Search"}
  • The square brackets hold the icon name: lowercase Latin letters, digits and _, as in the list of names.
  • Docara checks the name against the list. If there is no such name, for example :icon[setings], the build stops with the error CONTENT_COMPONENT_ICON_UNKNOWN and shows the file and line — otherwise the reader would see the word itself instead of the icon. The error is described in the error code reference.
  • Names in HTML examples and in Smart component parameters are not checked: an icon with an unknown name is shown there as text.

All icon names

To find an icon, open the list and use the browser’s find-in-page (Ctrl + F or ⌘ + F): it opens the list by itself. To see what an icon looks like, use fonts.google.com/icons: the names are the same there.

Variants

Style

family picks the family: outlined is an outline, rounded is rounded, sharp is sharp. weight picks the stroke weight, filled=true the fill.

check_circle

Size

size picks a step from the SIMAI Framework scale.

Container and colour

container=square or container=circle puts the icon on a container. Its look is set by variant, its colour by scheme.

bolt schema devices

States

How icons load

So that the page does not download anything extra, the icons are stored in several files.

  • Frequent icons. A small font with the most frequent outlined icons of regular weight loads together with the page.
  • Static catalogue. The other combinations are stored in 18 files: three families, three weights, with and without fill. Each file holds all 3926 icons and weighs 0.26–0.45 MB. The browser downloads only the files it needs.
  • Full font. For anything not in the catalogue, the browser loads the family’s full variable font — 3.5–5.3 MB.

:icon[...] always makes do with the static catalogue. The full font is needed only when an HTML example, a Smart component or the site styles ask for something the catalogue lacks:

  • the thin or bold weight (the Framework classes sf-icon-thin and sf-icon-bold);
  • a custom grade (--sf-icon--grade, the catalogue has only 0);
  • a custom optical size (--sf-icon--optical-size, the catalogue has only 24).

Such a page becomes several megabytes heavier, so stay within the catalogue unless you have a good reason.

Accessibility

  • Without label an icon is decoration: screen readers skip it. That is right when there is text next to it.
  • If the icon carries meaning on its own, set label: “Done”, “Search”.
  • Do not convey meaning by colour alone: add a word to a status icon.

Parameters

Parameter Values Default Sets
size 1/3, 1/2, 1, 2, 3 1/2 The size step of the icon.
family outlined, rounded, sharp outlined The style: outlined is an outline, rounded is rounded, sharp is sharp.
weight light, regular, medium regular The stroke weight of the icon.
filled true, false false The filled variant of the icon instead of the outlined one.
container none, square, circle none The container under the icon: none, a square or a circle.
variant auto, plain, main, tonal, outline auto The container look: auto follows the context, plain has no background, main is filled, tonal has a soft background, outline has a border.
scheme primary, secondary, tertiary, neutral, info, success, warning, danger, on-surface primary The colour of the icon and the container from the SIMAI Framework palette.
label string — The icon’s name for screen readers. Without it the icon counts as decoration.

See also