SPID/CIE button component

Opinionated component to support SPID and CIE login buttons according to the Italian government's standards.

Warning

the CIE button is still under development

This project is inspired by italia/spid-sp-access-button, with a few key differences:

• It is English-first: while the buttons are provided in Italian as well, the language of the project is English, please refrain from asking any question in a language other than that.
• It is written in TypeScript and agnostic to any framework (e.g. no jQuery dependency)
• It is provided as a standard npm package and can be used in any project
• It is designed to be easily customizable via CSS variables (see Usage)
• It takes into account modern standards for accessibility and usability (e.g. it is keyboard navigable, screen reader friendly, dark-mode compatible, it scales up and down with the browser's zoom level) and, as such, it does not support Internet Explorer.
• It takes sensible care of performances (e.g. only the required font glyphs are loaded), i.e. the bundle size is approx ~95% smaller than italia/spid-sp-access-button.
• It supports SSR, to minimize the Javascript code delivered to the client

Usage

Installation

npm install spid-cie-button
# or
yarn add spid-cie-button
# or
pnpm add spid-cie-button

APIs

The button component exposes the following APIs:

For parts that can be rendered on the server:

import { renderButton, renderDialog, renderHead } from "spid-cie-button/server";

const head = renderHead(); // returns the style tag, that should be included in the head of the page to avoid layout shifts
const button = renderButton({ lang: "it", type: "spid" }); // returns the HTML of the button element, with the specified language ("it" or "en") and type ("spid" vs "cie")

const rpEndpoint = (idp: string) => `https://example.com/spid?idp=${idp}`;
const dialog = renderDialog({ lang: "it", rpEndpoint }); // returns the HTML of the SPID dialog, with the specified language ("it" or "en") and where the actions are controlled by the `rpEndpoint` function

Render dialog accepts extra options to control whether demo and validator endpoint should be added or not:

export type DialogInputExtraOptions = {
  targetSelf?: boolean; // whether it should open a new page on provider click (target='_blank' vs target='_self') or not
  withDemo?: boolean; // whether it should add the demo provider or not
  withValidator?: boolean; // whether it should add the validator provider or not
};

Note that if both withDemo and withValidator are true, an extra Demo provider with validator mode is added.

For the interactions client-side, the following API is available:

import { initDialog } from "spid-cie-button";

initDialog(); // initializes the dialog, making it interactive

The following env variable adds a Demo IDP to the list of IDPs:

VITE_SPID_DEVELOPMENT_MODE=true

Style Customization

To control the style, the following CSS variables are available:

  --spid-button-background;  /* controls the background of the button */
  --spid-button-color;      /* controls the text color of the button */
  --spid-button-background-hover; /* controls the background of the button on hover */
  --spid-button-background-active; /* controls the background of the button when active/selected */
  --spid-button-color-active; /* controls the text color of the button when active/selected */
  --spid-button-scale; /* controls the scale of the button, change it to increase/reduce the button size (default: 1; numeric value) */

  --spid-base-img-size; /* default: 3rem; controls the size of the SPID and CIE logos */

Example

React/Next.js

In a React/Next.js project, you can use the following code to render the button and the dialog:

// SpidButton.ts, note that it could be a Next.js server component
import { renderButton, renderDialog, renderHead } from "spid-cie-button/server";
import { initDialog } from "spid-cie-button";

export default function SpidButton() {
  const head = renderHead();
  const button = renderButton({ lang: "it", type: "spid" });
  const rpEndpoint = (idp: string) => `https://example.com/spid?idp=${idp}`;
  const dialog = renderDialog({ lang: "it", rpEndpoint });
  useEffect(() => {
    initDialog();
  }, []);
  return (
    <div>
      {head}
      <div>{button}</div>
      <div>{dialog}</div>
      <script>initDialog();</script>
    </div>
  );
}

Vue/Nuxt 3+

In a Vue/Nuxt 3+ project, you can use the following code to render the button and the dialog:

<script setup>
import { initDialog } from "spid-cie-button";
import { renderButton, renderDialog, renderHead } from "spid-cie-button/server";

const head = renderHead();
const button = renderButton({ lang: "it", type: "spid" });
const rpEndpoint = (idp: string) => `https://example.com/spid?idp=${idp}`;
const dialog = renderDialog({ lang: "it", rpEndpoint });

const html = head + button + dialog;
// in Nuxt, the server part could be in a /api/ endpoint or in a server component

onMounted(() => initDialog());
</script>

<template>
  <form>
    <section v-html="html">
  </form>
</template>

Development

After cloning run the following commands:

pnpm install

Then, to start the development server:

pnpm dev

To include the demo endpoint in the list of IDPs, you can run the following command:

VITE_SPID_DEVELOPMENT_MODE=true pnpm dev