Valency
🤔 What is Valency?
Valency is a tool to manage and serve design assets.
- Design assets managed with Valency are served for use over a CDN.
📦 Install
npm install @valencyhq/valency --saveTable of Contents
🧪 Quick start
<!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>
👨🎨 Usage
The following ways you can use assets served by Valency.
🌐 Client-side JavaScript
1. Install
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.
2. Include
Include valency.js or valency.min.js with a <script> tag:
3. Use
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>4. Setup & Replace
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().
🖋 SVG Sprites & Icons
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
1. Usage
<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>
⚛️ React
There is a wrapper library for React, have a look at react-valency.
🎏 Figma
Valency is available as a Figma plugin. To use the plugin, log in to your Figma and install it. Get it now!
⚙️ API Reference
valency.get(assetName, config?)
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.get() shorthand properties
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.png
valency.replace(config?, document?)
All 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.
valency.loadSprite(config?)
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.
valency.getConfig(otherConfig?)
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.
valency.setConfig(otherConfig)
Use to globally update configuration.
👨🔧 Contributing
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
🧾 License
Valency is licensed under the MIT License.