Installation
You can load Lynk via CDN or by installing it locally. If you’re using a framework, make sure to check out the pages for React, Vue, and Angular for additional information.
CDN Installation (Easiest)
The experimental autoloader is the easiest and most efficient way to use Lynk. A lightweight script watches the DOM for unregistered Lynk elements and lazy loads them for you — even if they’re added dynamically.
While convenient, autoloading may lead to a Flash of Undefined Custom Elements. The linked article describes some ways to alleviate it.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@uplynk/lynk-design@1.0.0/cdn/themes/light.css" /> <script type="module" src="https://cdn.jsdelivr.net/npm/@uplynk/lynk-design@1.0.0/cdn/lynk-autoloader.js"></script>
The traditional CDN loader registers all Lynk elements up front. Note that, if you’re only using a handful of components, it will be much more efficient to stick with the autoloader. However, you can also cherry pick components if you want to load specific ones up front.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@uplynk/lynk-design@1.0.0/cdn/themes/light.css" /> <script type="module" src="https://cdn.jsdelivr.net/npm/@uplynk/lynk-design@1.0.0/cdn/lynk.js" ></script>
Dark Theme
The code above will load the light theme. If you want to use the
dark theme instead, update the stylesheet as shown below
and add <html class="lynk-theme-dark">
to your page.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@uplynk/lynk-design@1.0.0/cdn/themes/dark.css" />
Light & Dark Theme
If you want to load the light or dark theme based on the user’s prefers-color-scheme
setting,
use the stylesheets below. The media
attributes ensure that only the user’s preferred theme
stylesheet loads and the onload
attribute sets the appropriate
theme class on the <html>
element.
<link rel="stylesheet" media="(prefers-color-scheme:light)" href="https://cdn.jsdelivr.net/npm/@uplynk/lynk-design@1.0.0/cdn/themes/light.css" /> <link rel="stylesheet" media="(prefers-color-scheme:dark)" href="https://cdn.jsdelivr.net/npm/@uplynk/lynk-design@1.0.0/cdn/themes/dark.css" onload="document.documentElement.classList.add('lynk-theme-dark');" />
Now you can start using Lynk!
npm installation
If you don’t want to use the CDN, you can install Lynk from npm with the following command.
npm install @uplynk/lynk-design
It’s up to you to make the source files available to your app. One way to do this is to create a route in
your app called /lynk
that serves static files from
node_modules/@uplynk/lynk-design
.
Once you’ve done that, add the following tags to your page. Make sure to update href
and
src
so they point to the route you created.
<link rel="stylesheet" href="/lynk/dist/themes/light.css" /> <script type="module" src="/lynk/dist/lynk.js"></script>
Alternatively, you can use a bundler.
Setting the Base Path
Some components rely on assets (icons, images, etc.) and Lynk needs to know where they’re located. For
convenience, Lynk will try to auto-detect the correct location based on the script you’ve loaded it from.
This assumes assets are colocated with lynk.js
or lynk-autoloader.js
and will
“just work” for most users.
However, if you’re cherry picking or bundling Lynk, you’ll need to set the base path. You can do this one of two ways.
<!-- Option 1: the data-lynk attribute --> <script src="bundle.js" data-lynk="/path/to/lynk/dist"></script> <!-- Option 2: the setBasePath() method --> <script src="bundle.js"></script> <script type="module"> import { setBasePath } from '@uplynk/lynk-design/dist/utilities/base-path.js'; setBasePath('/path/to/lynk/dist'); </script>
Referencing Assets
Most of the magic behind assets is handled internally by Lynk, but if you need to reference the base path
for any reason, the same module exports a function called getBasePath()
. An optional string
argument can be passed, allowing you to get the full path to any asset.
<script type="module"> import { getBasePath, setBasePath } from '@uplynk/lynk-design/dist/utilities/base-path.js'; setBasePath('/path/to/assets'); // ... // Get the base path, e.g. /path/to/assets const basePath = getBasePath(); // Get the path to an asset, e.g. /path/to/assets/file.ext const assetPath = getBasePath('file.ext'); </script>
Cherry Picking
Cherry picking can be done from the CDN or from npm. This approach will load only the components you need up front, while limiting the number of files the browser has to download. The disadvantage is that you need to import each individual component.
Here’s an example that loads only the button component. Again, if you’re not using a module resolver, you’ll need to adjust the path to point to the folder Lynk is in.
<link rel="stylesheet" href="/path/to/lynk/dist/themes/light.css" /> <script type="module" data-lynk="/path/to/lynk/dist"> import '@uplynk/lynk-design/dist/components/button/button.js'; // <lynk-button> is ready to use! </script>
You can copy and paste the code to import a component from the “Importing” section of the component’s documentation. Note that some components have dependencies that are automatically imported when you cherry pick. If a component has dependencies, they will be listed in the “Dependencies” section of its docs.
Bundling
Lynk is distributed as a collection of standard ES modules that all modern browsers can understand. However, importing a lot of modules can result in a lot of HTTP requests and potentially longer load times. Using a CDN can alleviate this, but some users may wish to further optimize their imports with a bundler.
To use Lynk with a bundler, first install Lynk along with your bundler of choice.
npm install @uplynk/lynk-design
Now it’s time to configure your bundler. Configurations vary for each tool, but here are some examples to help you get started.
Once your bundler is configured, you’ll be able to import Lynk components and utilities.
import '@uplynk/lynk-design/dist/themes/light.css'; import '@uplynk/lynk-design/dist/components/button/button.js'; import '@uplynk/lynk-design/dist/components/icon/icon.js'; import '@uplynk/lynk-design/dist/components/input/input.js'; import '@uplynk/lynk-design/dist/components/rating/rating.js'; import { setBasePath } from '@uplynk/lynk-design/dist/utilities/base-path.js'; // Set the base path to the folder you copied Lynk's assets to setBasePath('/path/to/lynk/dist'); // <lynk-button>, <lynk-icon>, <lynk-input>, and <lynk-rating> are ready to use!
Avoiding auto-registering imports
By default, imports to components will auto-register themselves. This may not be ideal in all cases. To import just the component’s class without auto-registering it’s tag we can do the following:
- import LynkButton from '@uplynk/lynk-design/dist/components/button/button.js'; + import LynkButton from '@uplynk/lynk-design/dist/components/button/button.component.js';
Notice how the import ends with .component.js
. This is the current convention to convey the
import does not register itself.
danger While you can override the class or re-register the lynk class under a different tag name, if you do so, many components won’t work as expected.
The difference between CDN and npm
You’ll notice that the CDN links all start with /cdn/<path>
and npm imports use
/dist/<path>
. The /cdn
files are bundled separately from the
/dist
files. The /cdn
files come pre-bundled, which means all dependencies are
inlined so you do not need to worry about loading additional libraries. The /dist
files
DO NOT come pre-bundled, allowing your bundler of choice to more efficiently deduplicate
dependencies, resulting in smaller bundles and optimal code sharing.
TL;DR:
@uplynk/lynk-design/cdn
is for CDN users@uplynk/lynk-design/dist
is for npm users
This change was introduced in v1.0.0
to address issues around installations from npm loading
multiple versions of libraries (such as the Lit) that Lynk uses internally.