import React from 'react';
import { md, code, Props, Example } from '@kalamazoo/docs';
export default md`
### Custom Icons
If you need to render an icon that is not in our current set, and adding it
does not make sense, you can render a custom icon instead. We assume here that
the SVG's contents will be exported from a \`.js\` file, or
be written in a React context, so we need to sanitize our SVGs for that use-case.
First you will need to import the Icon component itself. The default export
of the package is this component, however you can use the same technique used with
individual icons to stop application bloat, and import just the component itself
using the following:
${code`import Icon from '@kalamazoo/icon/dist/cjs/components/Icon'`}
This icon has the same props as all icons. See the bottom of this page for those.
### Gotchas of generating your custom SVG
Icon uses svgs as glyphs, and there are certain rules we expect the glyphs to
adhere to so that they work correctly:
- the glyph is 24px by 24px
- the fill property of g will be set to 'currentColor', which will allow it to
be styled using the \`primaryColor\` prop.
- If you want part of your svg to be colored using the \`secondaryColor\` it
shuold have its fill property set to 'inherit'.
- custom icons should have \`focusable="false"\` and \`role="presentation"\`.
See the example below of us using a custom icon. If you want to remix it to
test out your own icon, view the example [here](/packages/core/icon/example/IconCustomExample)
and click on the \`sandbox\` link.
${(
)}
### SVGs from sketch
If you are exporting an svg from sketch, it will include a large amount of
metadata that you won't need. You will likely need to manually adjust the file.
There are several other optimisations that can be done to svgs. Here is an example
of one of our raw svg icons:
${code`
`}
vs the same icon after we have stripped it down:
${code`
`}
We use the \`SVGO\` package to clean these svgs, with several custom extensions
for our workflow. Here is what ur SVGO config looks like:
${code`
new SVGO({
multipass: true,
plugins: [
{ removeTitle: true },
{ removeDesc: { removeAny: true } },
{ cleanupIDs: true },
{ collapseGroups: true },
{ removeXMLNS: true },
{ removeNamespacedAttributes },
{ replaceSketchHexColors },
],
});
`}
The last two plugins are custom plugins we have written. The first removes
attributes with a namespace (e.g. xmlns:link, ns:foo, ...), while the second
replaces hex colors with 'currentColor' or 'inherit', depending on the color value.
If you only need to do this once, you may want to make the final changes by hand.
If you predict doing this multiple times, it may be worth copying our plugins
or writing your own.
Using this SVGO configuration should get you most of the way there, however
you will need to make sure you remove any attributes not supported in React. In
particular, attributes such as \`xmlns:link\` will cause React parsing to fail.
${(
)}
`;