npm package: @mobielnl/elements
Description: Mobiel.nl Elements - React component library for partner websites
Latest version: 0.12.13

# 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](https://elements.mobiel.nl).

## Contributing

Only Websend developers can currently contribute. See [Contributing Guide](https://elements.mobiel.nl/?path=/docs/contributing--docs).

## Getting Started

View our comprehensive [Getting Started](https://elements.mobiel.nl/?path=/docs/getting-started--docs) 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:

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

#### Usage

```tsx
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.

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

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

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

### For non-React projects

```html
<!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.

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

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

2. 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).

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

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

3. 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%).

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

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

4. Overriding Classes

You can customize component styling using the `classNames` prop.

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