Oombla DocsMenuoombla.com

React & Vue components

The base template for exporting assets as React or View components

The component template class is used to build the React and Vue components. Whereas the Base64/MiniSVG template class has a 1:1 relationship between the assets being exported and the collection of entities, the Component class may combine multiple assets into a single entity if it has been set up for variants.

Put another way, when thinking about the final template rendering stage for the Base64/MiniSVG class you can think of it in terms of assets. If you are exporting 20 assets you can think of 20 template renders for each asset. For the Component class you must think of the template rendering stage in terms of components, not assets. To use the same example, if you are exporting 20 assets, but five of them are variants of the same asset (that is, a default and four alternatives), there will be 15 template renders — one for each component, not asset.

There are four top-level props that are made available for each template render:

  • name <string>
  • svg <object>
  • variantSvgs <array>
  • variants <object>

name

The name prop is a string that contains the component name. It is in PascalCase and should always have content. In the base templates you will see it rendered with a direct output command:

<%= name %>

svg

The svg prop is an object that contains the data for the default SVG state. If it is a single asset export then all of the export data will be contained here and variantSvgs and variants will be empty. In a group of assets being exported, if this particular component has no variants, then like the single asset export all of the data will be in svg. For components with variants, the svg object represents the default state of the component and therefore should be used as a default state in conditional rendering scenarios. It will always have data unless something has been corrupted in the original SVG.

It contains the following properties:

  • contents is a string that contains the inner path data for the SVG, that is, everything between the <svg> and </svg> tags (excluding the top-level <svg> tags themselves).
  • defaultFill is a string and contains the color value of the asset if the asset has a uniform color.¹ If there are no fills or strokes, if all the fill and/or stroke values are none, or if there are unequal fills anywhere in the SVG then this value is undefined.
  • attributes is an object that contains a collection of attributes that were extracted from the asset’s top-level <svg> tag.

The attributes object contains the following properties:

  • fill: The original fill value, if it existed.
  • width: The original width value, if it existed.
  • height: The original height value, if it existed.
  • viewBox: The original viewBox coordinates, if they existed.
  • xmlns: The original xmlns value, if it existed.
  • other: Any other attributes that existed on the SVG (outside of the five above) are parsed and stored here.

It should be assumed that all of these properties have the potential to be empty; and most of the time it is likely that the other property will be empty. However, if other is used in the templates it should be set to render as a string of pre-rendered properties and values as opposed to the other values in the attributes object which represent just the values. A quick code example is given below.

Original SVG:

<svg
  width="32"
  height="32"
  viewBox="0 0 32 32"
  fill="black"
  data-type="icon"
  xmlns="http://www.w3.org/2000/svg"
>
...
</svg>

The attributes object will look like this:

{
  fill: "none",
  height: "32",
  other: "data-type=\"icon\"",
  viewBox: "0 0 32 32",
  width: "32",
  xmlns: "http://www.w3.org/2000/svg"
}

variantSvgs

variantSvgs is an array that will be empty if there are no variants for the component. If there are variants, it will contain a collection of objects that follow the same structure as svg outlined above. However, in addition to the properties outlined for svg above, there will be an extra property for each object called variants which is an array that contains objects of this structure:

{
  key: variantKey,
  value: variantValue
}

This variants array can be used to construct the conditional statement used to render this particular variant. For example, in the base React templates it is used like so (simplified slightly for clarity):

if (
  <% variantSvg.variants.map((variant, i) => { %>
    <%= variant.key %> === '<%= variant.value %>'<%= (i < variantSvg.variants.length - 1) ? ' && ' : '' %>
  <% }) %>
) {
  ...
}

In the above example, variantSvg is an object in the variantsSvgs collection. Its variants array of objects is being used to construct a conditional statement for its render (the ternary at the end is there in the case of multiple variants conditions). The final render would look something like this:

if (direction === 'left' && type === 'double') {
  ...
}

variants

The top-level variants property (not to be confused with the variants array found in the objects in variantSvgs) is built from all the data in variantSvgs and is an object with the available variants as the object keys with an array of potential values for each variants as their value. If variantSvgs is empty, variants is false.

This object can be used to list the potential variants keys as props in object destructuring for example.

Footnotes

  1. An asset is determined to have a uniform color if all the fill and/or stroke values in the <svg> element (including all the <path> data, etc.) are equal. In addition to the color value being assigned to defaultFill, if the color of the icon is uniform, all of the fill properties are removed from the inner contents of the SVG so that a single fill attribute can be applied to the parent <svg> element and targeted thusly for hover, focus and active styles. Further, the stroke attribute is also evaluated to determine if the the icon is of uniform color. However, unlike the fill attributes, the stroke attributes are left intact and the the value replaced with a conditional value of either rendering the custom color prop that is passed or falling back to the default value if no color prop is defined. Further style rules can be written to also target the stroke values for hover, focus and active states if desired. At this time, dynamic stroke values on assets is not considered a fully supported feature of the plugin.