@planningcenter/symbol
v4.0.0-alpha.2
Published
A component for presenting external SVG symbols via file-loader
Downloads
7,016
Readme
@planningcenter/symbol
Symbol
makes working with external resources SVGs painless, accessible, and repeatable.
Explanation
@planningcenter/icons
' primary export are SVG sprites.
They're desigen consumed with <use>
tags.
But use
tags still need a wrapping <svg>
element, default styling (size and color), and contextually relevant accessibility attributes like <title>
and <description>
.
Symbol
ties all that into a single React component with just three props.
What it does
symbol
lets familiar, standard external svg syntax for reference:my-icons.svg#smile"
title
lets you describe the what the image means and maps to a<title>
tag with uniquearia-labelledby
identifiersdesc
lets you describe what the image looks like and maps to a<description>
tag with uniquearia-labelledby
identifiersclassName
does as you'd expect but also includes our default.symbol
class- all other SVG properties, like
role
andaria-hidden
are passed thru as needed
Installation
Most apps are setup with a component that hold a dictionary of path urls, export an Icon
component, and modify path
(where needed):
import Symbol from "@planningcenter/symbol";
import general from "@planningcenter/icons/sprites/general.svg";
import people from "@planningcenter/icons/sprites/people.svg";
let icons = {
general,
people,
};
export default function Icon({ symbol: s, ...platformProps }) {
let [collection, symbol] = s.replace(".svg", "").split("#");
let path = `${icons[collection]}`;
return <Symbol symbol={`${path}#${symbol}`} {...platformProps} />;
}
Usage
With a setup like that in Installation, you can use the component with these outcomes:
default
This will show the image but provide nothing to screen readers.
Accessibility tools will rais an error that you should either hide the icon from the accessibility tree or add a title
.
<Icon symbol="general#show-eye" />
aria-hidden
Adding aria-hidden
removes the element from the accessiblity tree, indicating that you intentionally don't want anything read.
<Icon symbol="general#show-eye" aria-hidden />
title
Anything added to title
will be read by screen readers and (by default) shown as an in-browser tooltip.
This text should describe the intent, not the icon.
<Icon symbol="general#show-eye" title="This group is public" />
<Icon symbol="general#star" title="Favorited event" />
<Icon symbol="general#right-chevron" title="Next page" />
description
Anything added to description
will be read by screen readers but not shown as an in-browser tooltip.
Descriptions on SVGs are customarily used to describe the image itself.
It's rare that you'll use this.
<Icon symbol="general#show-eye" description="An eye that's open" />
Escape hatches
Up to v11 of @planningcenter/icons
, all symbols had a <title>
present.
It wasn't a great title, just the name of the icon.
But it gave us enough to feel like we providing a sensible fallback to users of assistive technologies.
That wasn't actually correct.
A change to Adobe Illustrator's default exports forced us to investigate those assumptions and make some corrections.
The new Symbol
API gives you full control over what is read by screenreaders.
However, it no longer provides icon names as default.
Mostly because the internal names didn't provide contextual value when read.
The ideal path forward is to provide meaningful title
s — where appropriate — or using aria-hidden
— where icons don't need to be read.
However, if (for some reason), you need to quickly get back to the previous behavior, there is an a temporary escape hatch.
import { ForceTitleContext } from "@planningcenter/symbol"
export function MyView() {
return () {
<ForceTitleContext.Provider value={true}>
<main>
...
</main>
</ForceTitleContext.Provider>
}
}
I'll repeat that this is a temporory escape hatch — where the previous behavior was preferred for an entire view, while more nuanced improvements are made.
It will not be present in the next version.