Lion

Website · Fundamentals · Guides · Components · Blog

Lion is a set of highly performant, accessible and flexible Web Components!

They provide an unopinionated, white-label layer that can be extended to your own layer of components.

• High Performance: Focused on great performance in all relevant browsers with a minimal number of dependencies.
• Accessibility: Aimed at compliance with the WCAG 2.2 AA standard to create components that are accessible for everybody.
• Flexibility: Provides solutions through Web Components and JavaScript classes which can be used, adopted and extended to fit all needs.
• Modern Code: Lion is distributed as pure es modules.
• Exposes functions/classes and Web Components: Ships a functionality in it's most appropriate form.

Note: Our demos may look a little bland but that is on purpose. They only come with functional stylings. This makes sense as the main use case is to extend those components and if you do you do not want to override existing stylings.

Explore the Lion Guides  ▶

Table of Contents

• Astro migration
  • Astro how to
  • Issues which are not caused by migration
• Installation
• How to use
  • Extend a web component
  • Use a JavaScript system
  • Use a Web Component
• Issues
• Feature request
• Content
• Technologies
• Rationale
• Coding guidelines
• How to contribute
• Site deployment
• Contact

Astro migration

• Keep using /docs on the root level as we used it in the master branch. The documentation is copied into Astro related directories on npm run start and when when anything in /docs is updated.
• Replace manually all references to assets in all md files so that we imply that the path is produced from the directory where the md file is located. F.e. new URL('../src/wa-combobox/assets/obama.jpeg', import.meta.url).href; should new URL('./src/wa-combobox/assets/obama.jpeg', import.meta.url).href;. Note double dot is replaced with one dot. See this PR for the reference.
• Rename all *.mjs files to *.js ones if they are used by mdjs examples

Astro how to

• To start in dev mode run npm run start
• To start in production mode:
  • Run npm run build
  • Run npm run preview

Issues which are not caused by the migration (not to be fixed now)

• There is a browser console error on collapsible page:

  __mdjs-stories--use-cases.js:40 Uncaught TypeError: shadowRoot.getElementById is not a function
  

  Note. There is the same error on master. This issue is not caused by the migration

How to install

npm i @lion/ui

Temporary phone-number metadata workaround

We temporarily vendor [email protected], rebuilt from Google's libphonenumber v9.0.41, instead of the registry dependency. This includes updated phone-number metadata, such as the French Guiana premium-rate example +594890123456, which the previous [email protected] rejected. We keep this workaround until the next upstream awesome-phonenumber release incorporating the required metadata is available.

The private workspace packages-node/awesome-phonenumber contains pinned fork and Google JavaScript sources, not a prebuilt distribution. Its build verifies source checksums, compiles with Closure ADVANCED and bundles ESM with Rollup using the fork's inputs and options. npm run types --workspace @lion/ui and npm pack build and copy the generated library into packages/ui/generated/awesome-phonenumber. Root postinstall builds these assets before source-analysis tools and browser tests; prepack also emits UI declarations for a fresh checkout. Wireit caches unchanged inputs; no source downloads occur during builds. @lion/ui has no awesome-phonenumber runtime or bundled dependency. Its package-private #awesome-phonenumber import maps types, ESM and CommonJS to the shipped assets, requiring no consumer browser import map. The legacy docs dependency keeps its separate registry version. MIT and Google's Apache-2.0 notices accompany both sources and generated assets. See source provenance and build requirements.

Run npm run test:node --workspace @lion/ui to pack Lion, install it into a fresh consumer outside the checkout with no overrides, and verify ESM, CommonJS, TypeScript 7 and 4.7.4, licenses, provenance, and French Guiana metadata. It also checks deterministic source rebuilds and rejection of modified sources. The install needs registry access for Lion's ordinary dependencies, not the phone library. npm run lint:phone-number-up-to-date verifies the maintained source inventory rather than incorrectly claiming registry freshness.

Once the next upstream awesome-phonenumber release includes the required metadata, restore the normal registry dependency in packages/ui/package.json, replace #awesome-phonenumber runtime/JSDoc imports with the registry name, and remove the private workspace, UI imports mapping, generated files entry and build/prepack hooks/helpers, including the root postinstall phone-build step. Remove the generated directory, source-lint integration, snapshot newline rule and third-party formatter/linter exclusions, then regenerate package-lock.json. Update the packaging test to check the registry dependency instead of generated assets. Keep the metadata regression test and rerun the phone tests, typechecks, and packed-consumer install check before removing this workaround documentation.

How to use

Extend a Web Component

This is the main use case for lion. To import component classes, and extend them for your own design system's components.

import { css } from 'lit';
import { LionInput } from '@lion/ui/input.js';

class MyInput extends LionInput {
  static get styles() {
    return [
      super.styles,
      css`
        /* your styles here */
      `,
    ];
  }
}
customElements.define('my-input', MyInput);

Use a JavaScript system

There's a couple of "systems" in lion which have a JavaScript API. Examples are localize, overlays, ajax, etc.

<script type="module">
  import { ajax } from '@lion/ui/ajax.js';

  ajax
    .fetch('data.json')
    .then(response => response.json())
    .then(data => {
      // do something with the data
    });
</script>

Use a Web Component

You can also use the lion elements directly, although this is likely not a common use case.

<script type="module">
  import '@lion/ui/define/lion-input.js';
</script>

<lion-input name="firstName"></lion-input>

Issues

If you encounter an issue with any of the packages we are offering please open a new bug issue. Be sure to include a description of the expected and the current behavior - additional adding a reproduction always helps.

Feature requests

When you have an idea on how we could improve, please check our discussions to see if there are similar ideas or feature requests. If there are none, please start your feature request as a new discussion topic. Add the title [Feature Request] My awesome feature and a description of what you expect from the improvement and what the use case is.

Content

Name	version	description
@lion/ui		Set of components
@lion/ajax		A small wrapper around fetch
Singleton-manager		A singleton manager provides a way to make sure a singleton instance loaded from multiple file locations stays a singleton. Primarily useful if two major version of a package with a singleton is used.
Babel plugin extend docs		A plugin which rewrites imports and templates according to a configuration. This enables the reuse of existing documentation from source packages while still using your extensions code.
Providence analytics		Providence is the 'All Seeing Eye' that generates usage statistics by analyzing code. It measures the effectivity and popularity of your software. With just a few commands you can measure the impact for (breaking) changes, making your release process more stable and predictable.
Publish docs		A tool that copies and processes your documentation (in a monorepo) so it can be published/shipped with your package.
Remark extend		A plugin for remark to extend markdown by importing from source files.
Rocket preset extend lion docs		When maintaining your own extension layer of lion you most likely want to maintain a similar documentation. Copying and rewriting the markdown files works, but whenever something changes you need copy and rewrite again. To do this automatically you can use this preset for rocket.

Technologies

Lion Web Components aims to be future-proof and use well-supported proven technology. The stack we have chosen should reflect this.

• lit
• npm
• Open Web Components
• Modern Web
• Mocha
• Chai
• ESLint
• prettier
• ES modules
• Lots and lots of tests

Supported browsers

Lion needs the native modal dialog: a modal overlay is opened with <dialog>.showModal(), and the browser is then what keeps the keyboard focus inside it and makes the rest of the page unreachable (for a screen reader too). There is no fallback for a browser that cannot do this, so IE11 and Safari 15 and older are not supported. Safari 16 is the oldest supported browser; Chrome, Edge and Firefox are supported for their last four versions. This is recorded in .browserslistrc.

Rationale

We know from experience that making high quality, accessible UI components is hard and time consuming: it takes many iterations, a lot of development time and a lot of testing to get a generic component that works in every context, supports many edge cases and is accessible in all relevant screen readers.

Lion aims to do the heavy lifting for you. This means you only have to apply your own Design System: by delivering styles, configuring components and adding a minimal set of custom logic on top.

Coding guidelines

Check out our coding guidelines for more detailed information.

How to contribute

Please note: This project uses Npm Workspaces. If you want to run all demos locally you need to get at least npm 7+ and install all dependencies by executing npm install.

Lion Web Components are only as good as its contributions. Read our contribution guide and feel free to enhance/improve Lion. We keep feature requests closed while we're not working on them.

Site deployment

The site is published to the gh-pages branch and served at https://lion.js.org. Collaborators with push permission to that branch can trigger a deploy with:

npm run deploy

That builds the portal (npm --prefix portal run build = astro build + the link pass, output in _site/) and pushes _site/ to gh-pages. The published layout:

• The Astro portal owns the site root (/), so every route the portal serves comes from _site/.
• The portal is its own package, outside the workspace (portal/): the astro toolchain is only needed to build the website, so no root npm install (CI included) pulls it in any more - a compromised package in that tree cannot run scripts during this repo's install. The root npm run build delegates to it, and npm run deploy still publishes _site/. Run npm install at the root once first: the portal renders the library from this checkout and the demos in docs/ resolve their imports from the repository's node_modules.
• The legacy rocket site lives at /prev and is frozen. Its build lives next to the portal in prev-portal/: the rocket tree is unmaintained, so it is kept out of the workspace too and no pipeline installs or builds it. cd prev-portal && npm install && npm run build writes _site/prev by hand. /prev is therefore the last published rocket tree, kept as it was (its root-absolute urls re-prefixed to /prev), and nothing regenerates it automatically.
• next/index.html redirects to / for links that still point at the pre-2026-04-23 layout.
• gh-pages deletes every file that is not in the directory it is given, so the deploy runs with -a (--add, never remove): without it a deploy silently drops /prev and that redirect. Astro's assets are content-hashed, so leftovers from earlier builds are inert; prune them by hand if the branch ever needs it.

Branch previews (test versions of the portal)

A branch preview is the portal built with another base url, published in a folder that carries the branch name. Nothing links to it, so it can be shared before a branch is merged.

cd portal
npm run preview                       # HEAD -> https://lion.js.org/next-preview/<branch-slug>/
npm run preview -- --no-push          # build and stage locally, do not publish
npm run preview -- --no-build         # reuse the _site/ that is already there
npm run preview -- --branch=feat/x    # preview another branch

The portal resolves all of its urls against import.meta.env.BASE_URL (set through ASTRO_BASE_URL), so a preview is the ordinary build with a different prefix; no other source changes are involved. next-preview/index.html lists the previews that are currently published.

The shared Pages site is public: a preview url is unlisted but not access controlled. For content that may not be public, stage it locally and expose it on the tailnet instead (npm run preview -- --target=local, then serve ~/portal-previews from a static server behind tailscale serve; the printed url is only reachable from devices in the tailnet).

Contact

Feel free to create a github issue for any feedback or questions you might have.