@mobielnl/elements

v0.12.18

Published

6 days ago

Mobiel.nl Elements - React component library for partner websites

0High
0Medium
0Low

t.beiten

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, default theme and 2 languages (Dutch and English).

Documentation

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

Contributing

Only Websend developers can currently contribute. See Contributing Guide.

Getting Started

View our comprehensive Getting Started guide for a step-by-step introduction to using Elements.

Installation

For React projects

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

Install the package via your preferred package manager:

pnpm add @mobielnl/elements
# or
npm install @mobielnl/elements
# or
yarn add @mobielnl/elements

Usage

import { ElementsRoot, ProductResults } from "@mobielnl/elements";
import "@mobielnl/elements/style.css"; // Import styles globally

export default function Example() {
  return (
    <ElementsRoot>
      <ProductResults productCategory="sim-only-proposition" />
    </ElementsRoot>
  );
}

All CSS styling is scoped under the <ElementsRoot> wrapper, which has the class "mobielnl-elements". 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>
  );
}

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>

    <!-- Include the Elements CSS 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@19/umd/react.production.min.js" crossorigin></script>
    <script
      src="https://unpkg.com/react-dom@19/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";

Scoped CSS styles

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>

Theming with CSS Variables

The library uses CSS custom properties (variables) for all its styling. You can override these variables to match your brand.

Color values are HSL triplets (h s% l%).

.mobielnl-elements {
  /* Override to light blue background */
  --elements-background: 220 67% 96%;

  /* Override to monospace font */
  --elements-font-family: monospace;
}

Overriding Classes

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} />;
}