Planning Center Icons

Accessible, scaleable, standard SVG icons for Planning Center apps

---

Looking for v1 docs? click here

TOC

• Contributing
• Platform setup and usage

Contributing

See CONTRIBUTING.md

Platform setup and usage

Anywhere

@planningcenter/icons can be used anywhere on the web. You simple need a link to a public path.

<svg role="img" title="down arrow icon" class="symbol">
  <use href="./path/to/general.svg#down-arrow"></use>
</svg>

When you do this, a few things are up to you:

• accessibily
• default styling
• cache busting

Follow the Rails and Webpack/React guides to get those things setup on one of our supported platforms.

Rails

Setup

Add this to config/initializers/assets.rb.

# Add node_modules as a known asset path
config.assets.paths << Rails.root.join('node_modules')

# Add assets to precompile step
# Add as many sprites as needed
Rails.application.config.assets.precompile += %w(
  @planningcenter/icons/sprites/general.svg
)

Add this helper.

module IconHelper
  def external_icon(name, **attrs)
    planningcenter_svg_use_tag(name, attrs) do |path|
      relativize_asset_path(asset_path(path))
    end
  end
end

planningcenter_svg_use_tag and relativize_asset_path are provided by the ministrycentered/interfaces gem. It's bundled into all Planning Center apps.

Usage

Once Rails is setup with the `external_icon` helper, it can be used it like so.

<%= external_icon("general#down-arrow") %>

By default external_icon uses the symbol class, included in this project.

We recommended styling icons from an ancestor. This helps to keep app-code separate from icon implementation:

<span style="color: blue; font-size: 20px">
  <%= external_icon("general#down-arrow") %>
</span>

You can add HTML attributes to the use tag via the helper. This can be handy for specially styled icons or those you target via JavaScript.

Rails, Webpacker, and React

Setup

Add the file-loader npm package (yarn add file-loader).

Once installed, add the requisite config to config/webpacker/environments. This tellos webpack how to handle required SVG files.

const { environment } = require("@rails/webpacker");

environment.loaders.append("file", {
  test: /\.svg$/,
  use: [
    {
      loader: "file-loader"
    }
  ]
});

module.exports = environment;

usage

With the `file-loader` setup above. You can use `import` to resolve digested paths to `.svg` assets.

import svgPath from "@planningcenter/icons/sprites/general.svg";

//=> "/packs/23besrhaoub-general.svg"

Add @planningcenter/symbol to you app (yarn add @planningcenter/symbol). This component handles the display of your SVG sprite, using use tags. It also gives you smart accessible defaults.

Add a component to your app that looks lomething like this.

import React from "react";
import Symbol from "@planningcenter/symbol";

import general from "@planningcenter/icons/sprites/general.svg";

let icons = {
  general
};

function ExternalIcon({ symbol: s, ...platformProps }) {
  const [collection, symbol] = s.replace(".svg", "").split("#");

  return (
    <Symbol symbol={`${icons[collection]}#${symbol}`} {...platformProps} />
  );
}

export default ExternalIcon;

Run bin/webpack-dev-server to get fresh assets in development.

With the implementation above you can used cached, accessible icons in React, like so.

import Icon from "./path/to/external_icon.js"

<Icon symbol="general#down-arrow">

We recommended styling icons from an ancestor. This helps to keep app-code separate from icon implementation:

<span style={{ color: "blue", fontSize: 20 }}>
  <%= external_icon("general#down-arrow") %>
</span>

You can add props to the use tag via the Icon component. This can be handy for specially styled icons or those you target via JavaScript (that's probably not a good idea but maybe you do it).

<Icon
  symbol="general#down-arrow"
  id="myIcon"
  class="my-special-icon"
>

Gatsby (most starters)

setup

add @planningcenter/icons and @planningcenter/symbol to your project:

yarn @planningcenter/icons @planningcenter/symbol

usage

import general from "@planningcenter/icons/sprite/general.svg"
import "@planningcenter/icons/css/symbol.css"
import Symbol from "@planningcenter/symbol"

function App() {
  return <Symbol symbol={`${general}#down-arrow`} />;
}

create-react-app

setup

add @planningcenter/icons and @planningcenter/symbol to your project:

yarn @planningcenter/icons @planningcenter/symbol

usage

import general from "@planningcenter/icons/sprite/general.svg"
import "@planningcenter/icons/css/symbol.css"
import Symbol from "@planningcenter/symbol"

function App() {
  return <Symbol symbol={`${general}#down-arrow`} />;
}

CodeSandbox

Examples

@planningcenter/icons, single SVG
@planningcenter/icons, SVG sprite

IE11 External Resource SVG polyfill — svg4everybody

Anywhere

<script src="/path/to/svg4everybody.js"></script>
<script>window.svg4everybody()</script>

Rails (.erb layout)

Setup (layout)

<%= javascript_include_tag "@planningcenter/icons/js/svg4everybody.js">
<script>
  window.svg4everybody()
</script>

Rails (sprockets)

//= require "@planningcenter/icons/js/svg4everybody.js
//= require_self

window.svg4everybody();

CHANGELOG

CHANGELOG
CHANGELOG-v1
CHANGELOG-v2