diff --git a/packages/icon/README.md b/packages/icon/README.md index 5261f31..c1c96af 100644 --- a/packages/icon/README.md +++ b/packages/icon/README.md @@ -21,13 +21,13 @@ Iconify Icon web component renders icons. Add this line to your page to load IconifyIcon (you can add it to `` section of the page or before ``): ```html - + ``` or ```html - + ``` or, if you are building a project with something like WebPack or Rollup, you can include the script by installing `iconify-icon` as a dependency and importing it in your project: @@ -48,6 +48,21 @@ That is it. Change `icon` attribute to the name of the icon you want to use. The Do you want to make your own icon sets? Everything you need is [available on GitHub](https://github.com/iconify): tools for creating custom icon sets, Iconify API application and documentation to help you. +## Advantages + +What are advantages of using IconifyIcon web component? + +Advantages of using Iconify components: + +- No need to pre-bundle icons. Pass icon name as parameter, component will load data for icon from public API and render it. +- Huge choice of icons, no icon fonts! +- Easy to style. All monotone icons use font color for color (`currentColor`) and font size for size (height is set to `1em`), making it easy to change color and size. + +Main advantage of web component over other implementations is shadow DOM. Using shadow DOM instead of inlining SVG has the following advantages: + +- Document's styles do not affect content of shadow DOM, so there are no conflicting styles. +- HTML served from server does not contain long code for icons. It only contains `` tags, which reduces document size. Frameworks that use SSR and hydration, using web component for icons means same HTML code generated on server and rendered in client, preventing potential hydration errors. Actual icon code is hidden in shadow DOM. + ## Full documentation This package is in development, documentation for it is not ready yet. @@ -100,6 +115,23 @@ You can also do that by applying style: > ``` +## Render modes + +Web component has several render modes, which can be changed by passing `mode` property: + +- `svg`: renders icon as ``. +- `bg`: renders icon as `` with background set to SVG. +- `mask`: same as `bg`, but uses masks instead, combined with `background-color: currentColor`, which results in icon rendered as background that uses text color. +- `style`: `bg` or `mask`, depending on icon content. + +Why are these modes needed? + +It solves issues with SVG 2 animations. Usually, when SVG contains animations, animations do not start until DOM is ready. This can be affected by small things like ad code failing to load, preventing animations from working and causing frustration to developers. However, this is not an issue if SVG is rendered as background - animations are ran instantly. Also performance of SVG 2 animations is much better when used as background or mask. Background is used when icon does not contain `currentColor`, so all colors are displayed properly. Mask is used when icon contains `currentColor`, so icon is used as mask for background that uses `currentColor`, so icon correctly follows `currentColor`. + +If background and masks are so good, why SVG mode is available? First issue is color: if icon has mix of `currentColor` and palette (please do not design icons like that, it is bad practice!), icon colors will be incorrect, so such icons should be rendered as ``. Second issue is performance of icons without animations. Animated icons do perform much better as background or mask, but icons without animation usually perform better as ``. + +What is default rendering mode? That depends on icon. If icon contains SVG 2 animation tags, icon is rendered as `` with background or mask (mask for icons that contain `currentColor`, background for other icons), otherwise icon is rendered as ``. + ## Iconify API When you use an icon font, each visitor loads an entire font, even if your page only uses a few icons. This is a major downside of using icon fonts. That limits developers to one or two fonts or icon sets. diff --git a/packages/icon/package-lock.json b/packages/icon/package-lock.json index f035f35..9ae5148 100644 --- a/packages/icon/package-lock.json +++ b/packages/icon/package-lock.json @@ -1,12 +1,12 @@ { "name": "iconify-icon", - "version": "0.0.1-dev", + "version": "0.0.2", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "iconify-icon", - "version": "0.0.1-dev", + "version": "0.0.2", "license": "MIT", "dependencies": { "@iconify/types": "^1.1.0" diff --git a/packages/icon/package.json b/packages/icon/package.json index bb4dd12..3279298 100644 --- a/packages/icon/package.json +++ b/packages/icon/package.json @@ -2,7 +2,7 @@ "name": "iconify-icon", "description": "Icon web component that loads icon data on demand. Over 100,000 icons to choose from", "author": "Vjacheslav Trushkin (https://iconify.design)", - "version": "0.0.1", + "version": "0.0.2", "license": "MIT", "main": "./dist/iconify-icon.cjs", "types": "./dist/iconify-icon.d.ts",