@mobielnl/elements

v0.10.1

Published

a day ago

Mobiel.nl Elements - React component library for partner websites

0High
0Medium
0Low

n.vansteenpaal

buitelaar

mobiel.nl mobielnl websend elements

Mobiel.nl Elements

A React component library built with Vite library mode. Ships ES and UMD bundles plus TypeScript types and a Mobiel.nl theme.

Documentation

To view the available elements and changelog, check out our Documentation.

Contributing

Only Websend developers can currently contribute. See Contributing Guide.

Installation

For React projects

You will need Node.js 18+ and React 19+.

Install with your preferred package manager (pnpm, npm, yarn, bun, etc.)

pnpm add @mobielnl/elements

Usage

import { ElementsRoot, ProductResults } from "@mobielnl/elements";
import "@mobielnl/elements/style.css"; // can also be imported in (global) CSS file

export default function Example() {
  return (
    <ElementsRoot>
      <ProductResults />
    </ElementsRoot>
  );
}

All CSS styling is scoped to this <ElementsRoot> wrapper, which is essentially a div with a "mobielnl-elements" class:

<div class="mobielnl-elements">{children}</div>

Components nested within this wrapper will inherit the styling. This is done so that it does not overwrite other CSS styling.

Shadow DOM (optional)

You can opt in for a Shadow DOM to isolate the CSS from your application's global styles.

It is possible to inject a CSS string or CSS path url into the Shadow DOM. The withShadowDOM prop accepts:

true - Enables Shadow DOM without injecting CSS (for advanced use-cases)
{ cssUrl: string } - Enables Shadow DOM and injects a stylesheet from the provided URL
{ css: string } - Enables Shadow DOM and injects CSS from a string

Important: When using Shadow DOM, you must provide a CSS URL or string that points to the Elements CSS so styles render inside the shadow root.

/* File: elements.css */
@import "@mobielnl/elements/style.css";

import { ElementsRoot, ProductResults } from "@mobielnl/elements";

export default function Example() {
  return (
    <ElementsRoot withShadowDOM={{ cssUrl: "/elements.css" }}>
      <ProductResults />
    </ElementsRoot>
  );
}

Custom Styling with Tailwind CSS

You can customize component styling using the classNames prop.

import { ProductResults, type ProductResultsClassNames } from "@mobielnl/elements";

const productResultsClassNames: ProductResultsClassNames = {
  propositionCard: {
    title: "text-5xl font-extrabold text-secondary",
    pricingSection: {
      monthlyFeeValue: "text-danger",
    },
  },
};

export default function Example() {
  return <ProductResults classNames={productResultsClassNames} />;
}

For non-React projects

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>MobielNL UMD Test</title>

    <!-- Default MobielNL Stylesheet -->
    <link rel="stylesheet" href="../dist/elements.css" />
  </head>
  <body>
    <!-- Wrapper class for scoped styling -->
    <div class="mobielnl-elements">
      <!-- HTML placeholder for rendering -->
      <div id="mobielnl-product-results"></div>
    </div>

    <!-- React and ReactDOM (UMD) -->
    <script src="https://unpkg.com/react@18/umd/react.production.min.js" crossorigin></script>
    <script
      src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"
      crossorigin
    ></script>

    <!-- MobielNL UMD bundle attaches global `Elements` -->
    <script src="../dist/elements.umd.cjs"></script>

    <!-- Render MobielNL ProductResults -->
    <script>
      const productResultsClassNames = {
        propositionCard: {
          title: "text-5xl font-extrabold text-secondary",
          pricingSection: {
            monthlyFeeValue: "text-danger",
          },
        },
      };

      ReactDOM.createRoot(document.getElementById("mobielnl-product-results")).render(
        React.createElement(Elements.ProductResults, { classNames: productResultsClassNames })
      );
    </script>
  </body>
</html>

Theme & Styling

Our compiled stylesheet uses HeroUI-compatible CSS custom properties.

Import the stylesheet at the top of your (global) CSS file.

@import "@mobielnl/elements/style.css";

All CSS styles and variables are scoped under the .mobielnl-elements class. Wrap where you render elements or use ElementsRoot (only React).

<div className="mobielnl-elements">
  <!-- Elements here -->
</div>

<ElementsRoot>{/*  Elements here  */}</ElementsRoot>

You can customize the theme with CSS variables on the wrapper or any ancestor.

Copy the token set and set your own theme. Color values are HSL triplets (h s% l%).
You can scope themes per element or toggle dark mode using data-theme.

Default theme

The default theme is the default HeroUI theme.

.mobielnl-elements {
  --elements-background: 0 0% 100%;
  --elements-overlay: 0 0% 0%;

  --elements-foreground-50: 0 0% 98.04%;
  --elements-foreground-100: 240 4.76% 95.88%;
  --elements-foreground-200: 240 5.88% 90%;
  --elements-foreground-300: 240 4.88% 83.92%;
  --elements-foreground-400: 240 5.03% 64.9%;
  --elements-foreground-500: 240 3.83% 46.08%;
  --elements-foreground-600: 240 5.2% 33.92%;
  --elements-foreground-700: 240 5.26% 26.08%;
  --elements-foreground-800: 240 3.7% 15.88%;
  --elements-foreground-900: 240 5.88% 10%;
  --elements-foreground: 201.81999999999994 24.44% 8.82%;

  --elements-content1: 0 0% 100%;
  --elements-content1-foreground: 201.81999999999994 24.44% 8.82%;
  --elements-content2: 240 4.76% 95.88%;
  --elements-content2-foreground: 240 3.7% 15.88%;
  --elements-content3: 240 5.88% 90%;
  --elements-content3-foreground: 240 5.26% 26.08%;
  --elements-content4: 240 4.88% 83.92%;
  --elements-content4-foreground: 240 5.2% 33.92%;

  --elements-default-50: 0 0% 98.04%;
  --elements-default-100: 240 4.76% 95.88%;
  --elements-default-200: 240 5.88% 90%;
  --elements-default-300: 240 4.88% 83.92%;
  --elements-default-400: 240 5.03% 64.9%;
  --elements-default-500: 240 3.83% 46.08%;
  --elements-default-600: 240 5.2% 33.92%;
  --elements-default-700: 240 5.26% 26.08%;
  --elements-default-800: 240 3.7% 15.88%;
  --elements-default-900: 240 5.88% 10%;
  --elements-default-foreground: 0 0% 0%;
  --elements-default: 240 4.88% 83.92%;

  --elements-primary-50: 212.5 92.31% 94.9%;
  --elements-primary-100: 211.84000000000003 92.45% 89.61%;
  --elements-primary-200: 211.84000000000003 92.45% 79.22%;
  --elements-primary-300: 212.24 92.45% 68.82%;
  --elements-primary-400: 212.14 92.45% 58.43%;
  --elements-primary-500: 212.01999999999998 100% 46.67%;
  --elements-primary-600: 212.14 100% 38.43%;
  --elements-primary-700: 212.24 100% 28.82%;
  --elements-primary-800: 211.84000000000003 100% 19.22%;
  --elements-primary-900: 211.84000000000003 100% 9.61%;
  --elements-primary-foreground: 0 0% 100%;
  --elements-primary: 212.01999999999998 100% 46.67%;

  --elements-secondary-50: 270 61.54% 94.9%;
  --elements-secondary-100: 270 59.26% 89.41%;
  --elements-secondary-200: 270 59.26% 78.82%;
  --elements-secondary-300: 270 59.26% 68.24%;
  --elements-secondary-400: 270 59.26% 57.65%;
  --elements-secondary-500: 270 66.67% 47.06%;
  --elements-secondary-600: 270 66.67% 37.65%;
  --elements-secondary-700: 270 66.67% 28.24%;
  --elements-secondary-800: 270 66.67% 18.82%;
  --elements-secondary-900: 270 66.67% 9.41%;
  --elements-secondary-foreground: 0 0% 100%;
  --elements-secondary: 270 66.67% 47.06%;

  --elements-success-50: 146.66999999999996 64.29% 94.51%;
  --elements-success-100: 145.71000000000004 61.4% 88.82%;
  --elements-success-200: 146.2 61.74% 77.45%;
  --elements-success-300: 145.78999999999996 62.57% 66.47%;
  --elements-success-400: 146.01 62.45% 55.1%;
  --elements-success-500: 145.96000000000004 79.46% 43.92%;
  --elements-success-600: 146.01 79.89% 35.1%;
  --elements-success-700: 145.78999999999996 79.26% 26.47%;
  --elements-success-800: 146.2 79.78% 17.45%;
  --elements-success-900: 145.71000000000004 77.78% 8.82%;
  --elements-success-foreground: 0 0% 0%;
  --elements-success: 145.96000000000004 79.46% 43.92%;

  --elements-warning-50: 54.55000000000001 91.67% 95.29%;
  --elements-warning-100: 37.139999999999986 91.3% 90.98%;
  --elements-warning-200: 37.139999999999986 91.3% 81.96%;
  --elements-warning-300: 36.95999999999998 91.24% 73.14%;
  --elements-warning-400: 37.00999999999999 91.26% 64.12%;
  --elements-warning-500: 37.02999999999997 91.27% 55.1%;
  --elements-warning-600: 37.00999999999999 74.22% 44.12%;
  --elements-warning-700: 36.95999999999998 73.96% 33.14%;
  --elements-warning-800: 37.139999999999986 75% 21.96%;
  --elements-warning-900: 37.139999999999986 75% 10.98%;
  --elements-warning-foreground: 0 0% 0%;
  --elements-warning: 37.02999999999997 91.27% 55.1%;

  --elements-danger-50: 339.13 92% 95.1%;
  --elements-danger-100: 340 91.84% 90.39%;
  --elements-danger-200: 339.3299999999999 90% 80.39%;
  --elements-danger-300: 339.11 90.6% 70.78%;
  --elements-danger-400: 339 90% 60.78%;
  --elements-danger-500: 339.20000000000005 90.36% 51.18%;
  --elements-danger-600: 339 86.54% 40.78%;
  --elements-danger-700: 339.11 85.99% 30.78%;
  --elements-danger-800: 339.3299999999999 86.54% 20.39%;
  --elements-danger-900: 340 84.91% 10.39%;
  --elements-danger-foreground: 0 0% 100%;
  --elements-danger: 339.20000000000005 90.36% 51.18%;

  --elements-font-family: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";

  --elements-font-size-tiny: 0.75rem;
  --elements-font-size-small: 0.875rem;
  --elements-font-size-medium: 1rem;
  --elements-font-size-large: 1.125rem;

  --elements-line-height-tiny: 1rem;
  --elements-line-height-small: 1.25rem;
  --elements-line-height-medium: 1.5rem;
  --elements-line-height-large: 1.75rem;

  --elements-radius-small: 8px;
  --elements-radius-medium: 12px;
  --elements-radius-large: 14px;

  --elements-divider: 0 0% 6.67%;
  --elements-divider-weight: 1px;
  --elements-border-width-small: 1px;
  --elements-border-width-medium: 2px;
  --elements-border-width-large: 3px;

  --elements-focus: 212.01999999999998 100% 46.67%;
  --elements-hover-opacity: .8;
  --elements-disabled-opacity: .5;

  --elements-box-shadow-small: 0px 0px 5px 0px rgb(0 0 0 / 0.02), 0px 2px 10px 0px rgb(0 0 0 / 0.06), 0px 0px 1px 0px rgb(0 0 0 / 0.3);
  --elements-box-shadow-medium: 0px 0px 15px 0px rgb(0 0 0 / 0.03), 0px 2px 30px 0px rgb(0 0 0 / 0.08), 0px 0px 1px 0px rgb(0 0 0 / 0.3);
  --elements-box-shadow-large: 0px 0px 30px 0px rgb(0 0 0 / 0.04), 0px 30px 60px 0px rgb(0 0 0 / 0.12), 0px 0px 1px 0px rgb(0 0 0 / 0.3);
}

/* Optional: dark theme overrides on the wrapper */
[data-theme="dark"].mobielnl-elements,
.mobielnl-elements[data-theme="dark"] {
  --elements-background: 0 0% 0%;
}

Notes

Colors are HSL triplets (h s% l%). Use a HSL converter if needed.
You can define multiple named themes using [data-theme="brand-x"] { ... } and switch at runtime.