Citrus UI

Propel's UI component library.

See what components are currently available in Storybook.

Questions? Ask for eng help in #unit-eng-frontend-libraries. Get answers to design or cross-functional questions in #wg-citrus-design-system.

Docs

| Page | Description | | -------------------------------------------------- | --------------------------------------- | | Development | Linting, testing, and adding components | | Style Guide | Guidelines for code styles |

Publishing

cd libs/citrus-ui
pnpm version patch   # or minor / major
pnpm publish --access restricted

pnpm version bumps package.json, auto-updates unpkg/CDN version references in examples/, and creates a git commit + tag.

Usage

citrus-ui publishes two builds:

| Build | File | Description | | ------- | -------------------- | --------------------------------------------------------------------------------- | | npm | dist/index.mjs | Dependencies externalized — for bundler-based projects | | CDN | dist/index.cdn.mjs | All dependencies bundled except vue and vue-router — for <script> tag usage |

Both builds share a single stylesheet: dist/styles.css (component styles + global styles including reset, fonts, shoelace theme, and utility classes).

npm / Bundler

import CitrusUi from '@propelinc/citrus-ui';
import '@propelinc/citrus-ui/dist/styles.css';

app.use(CitrusUi);

Icons

Components like CButton and CIconButton accept an icon prop that supports FontAwesome string syntax (e.g. :icon="['fas', 'check']"). For this to work, the icons must be registered with FontAwesome's library.

Import the icons entry point once in your app setup to register all Pro Solid, Regular, and Light icons:

import '@propelinc/citrus-ui/icons';

This is opt-in to avoid bundling ~3MB of icon data for apps that don't need string-based icon lookup. If you skip this import, you can still pass IconDefinition objects directly:

import { faCheck } from '@fortawesome/pro-solid-svg-icons';

<CButton :icon="faCheck">Confirm</CButton>

CDN

The CDN build only requires vue and vue-router to be loaded separately. Everything else (Shoelace, FontAwesome, dayjs, lodash, maska, scroll-into-view-if-needed, core-js, i18next) is bundled in.

Use the .prod.js ESM browser builds for both Vue and Vue Router. The non-prod vue-router build imports @vue/devtools-api, which will fail to resolve in a CDN/importmap context.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@propelinc/citrus-ui/dist/styles.css" />

<script type="module">
  import { createApp } from 'https://cdn.jsdelivr.net/npm/vue@3/dist/vue.esm-browser.prod.js';
  import {
    createRouter,
    createWebHistory,
  } from 'https://cdn.jsdelivr.net/npm/vue-router@4/dist/vue-router.esm-browser.prod.js';
  import CitrusUi from 'https://cdn.jsdelivr.net/npm/@propelinc/citrus-ui/dist/index.cdn.mjs';

  // Register all FontAwesome icons for string-based icon lookup (optional)
  import 'https://cdn.jsdelivr.net/npm/@propelinc/citrus-ui/dist/icons.cdn.mjs';

  const router = createRouter({
    history: createWebHistory(),
    routes: [
      /* ... */
    ],
  });

  const app = createApp({
    /* ... */
  });
  app.use(router);
  app.use(CitrusUi);
  app.mount('#app');
</script>