Valency is a tool to manage and serve design assets.
- Design assets managed with Valency are served for use over a CDN.
npm install @valencyhq/valency --save<!DOCTYPE html>
<html lang="en">
<title></title>
<script src="https://unpkg.com/@valencyhq/valency"></script>
<body>
<img data-valency="cat-dog" />
<script>
var valent = new Valency({
uid: 'your user ID',
project: 'your project ID',
library: 'Your library ID',
})
valent.replace()
</script>
</body>
</html>The following ways you can use assets served by Valency.
Note: If you intend to use Valency with a CDN, you can skip this installation step.
Install with npm.
npm install @valencyhq/valency --saveOr just copy valency.js or valency.min.js into your project directory. You don't need both valency.js and valency.min.js.
Include valency.js or valency.min.js with a <script> tag:
To use an icon on your page, add a data-valency attribute with the icon name to an element:
<img data-valency="man-dog" />
<object data-valency="man-dog"></object>
<div data-valency="man-dog">Your background image goes here</div>Setup Valency with your credentials. Call the valency.replace() method:
<script>
var valent = new Valency({
uid: 'Your user ID',
project: 'Your project ID',
library: 'Your library ID',
})
valent.replace()
</script>All elements that have a data-valency attribute, their src or data atrribute will be replaced with the assset's URL corresponding to their data-valency attribute value.
See the API Reference for more information about valency.replace().
Valency serves icons packed into a single SVG sprite.
If an icon in a icons library is not a vector
(PNG or JPG), it gets converted toSVG, then packed into the SVG sprite. For Valency to serve SVG Icon sprite for a library, the library's category must beicon
<svg
data-valency="icon-name"
width="24"
height="24"
fill="none"
stroke="currentColor"
></svg>
<!-- you can also use i tag -->
<i data-valency="icon-name"></i>Use data-valency-lib to set a library name if you don't want to use the default.
<svg
data-valency="icon-name"
data-valency-lib="icons-library-name"
width="24"
height="24"
fill="none"
stroke="currentColor"
></svg>
<i data-valency="icon-name" data-valency-lib="icons-library-name"></i>There is a wrapper library for React, have a look at react-valency.
Valency is available as a Figma plugin. To use the plugin, log in to your Figma and install it. Get it now!
Returns a URL to the provided assetName.
If
configargument is provided, it is used to generate the link instead of the default configuration set at instance ofValency.
Valency provides convenient shorthand properties to Valency.get() which provides an intuitive way to get an asset's URL.
The shorthand format goes like this:
valent.asset.<assetName>.url
valent.asset.<yourLibraryId>.<someAssetName>.url
valent.asset.<yourProjectId>.<yourLibraryId>.<someAssetName>.url
valent.asset.<yourUserId>.<yourProjectId>.<yourLibraryId>.<someAssetName>.urlLet's show some sample Valency.get() usage with it's shorthand equivalent.
const valent = new Valency({
uid: '9825624020',
project: 'PsSBtkjlQys',
library: 'LIB_i7J',
})
/** 🔖 EXAMPLE 1 **/
valent.get('blondeAvatar')
/**
* Shorthand 🤞
* valent.asset.<assetName>.url
*/
valent.asset.blondeAvatar.url
// returns https://cdn.valency.design/9825624020/PsSBtkjlQys/LIB_i7J/blondeAvatar
/** 🔖 EXAMPLE 2 **/
valent.get('03886')
/**
* Shorthand 🤞
* valent.asset.<assetName>.url
*/
valent.asset['03886'].url
// returns https://cdn.valency.design/9825624020/PsSBtkjlQys/LIB_i7J/03886
/** 🔖 EXAMPLE 3 **/
valent.get('latinoAvatar', {
library: 'LIB_3D_avatars',
})
/**
* Shorthand 🤞
* valent.asset.<libraryID>.<assetName>.url
*/
valent.asset.Lib_3D_avatars.latinoAvatar.url
// returns https://cdn.valency.design/9825624020/PsSBtkjlQys/LIB_3D_avatars/latinoAvatar
/** 🔖 EXAMPLE 4 **/
valent.get('spaceship', {
library: 'LIB_i3m',
project: 'pNASA',
})
/**
* Shorthand 🤞
* valent.asset.<projectID>.<libraryID>.<assetName>.url
*/
valent.asset.pNASA.LIB_i3m.spaceship.url
// returns https://cdn.valency.design/9825624020/pNASA/LIB_i3m/spaceship
/** 🔖 EXAMPLE 5 **/
valent.get('Mast Head.png', {
library: 'LIB_mcq',
project: 'pMaterial',
uid: '03786',
})
/**
* Shorthand 🤞
* valent.asset.<userID>.<projectID>.<libraryID>.<assetName>.url
*/
valent.asset['03786'].pMaterial.LIB_mcq['Mast Head.png'].url
// returns https://cdn.valency.design/03786/pMaterial/LIB_mcq/Mast Head.pngAll elements that have a data-valency attribute, their src atrribute will be replaced with the assset URL corresponding to their data-valency attribute value.
If
configis provided, it's merged with the base configuration. Note that whatever options contained in theconfigobject takes precedence over the base configuration when they're merged together.
If
documentis provided, it carries out replace on it instead ofwindow.document.
Loads the SVG sprite of a library into the DOM.
If
configis provided, it's merged with the base configuration. Note that whatever options contained in theconfigobject takes precedence over the base configuration when they're merged together.
Returns configuration object.
If
otherConfigis provided, it's merged with the base configuration. Note that whatever options set inotherConfigtakes precedence over the base configuration when they're merged together.
Use to globally update configuration.
For more info on how to contribute please see the contribution guidelines.
Caught a mistake or want to contribute to the documentation? Edit this page on Github
Valency is licensed under the MIT License.