Green Web Badge as Custom Element

Introduction

This library defines an HTML Custom Element to check and display a badge if your site passes the Green Web Check from The Green Web Foundation.

See https://github.com/thegreenwebfoundation/admin-portal/issues/234 for the original discussion that led to this library.

1. Installation

Install @vnphanquang/green-check with your package manager of choice (recommended):

pnpm add @vnphanquang/green-check
npm install @vnphanquang/green-check
yarn add @vnphanquang/green-check

[!NOTE] This method is recommended as it allows the green-check module to be part of your dependency tree and build process, making it easier to integrate into framework contexts, track version, and deploy with high availability (you are effectively self-hosting the module).

Alternatively, you may load the module via a CDN by adding to importmap in your html:

<script type="importmap">
  {
    "imports": {
      "@vnphanquang/green-check": "https://cdn.jsdelivr.net/npm/@vnphanquang/green-check/dist/index.js"
    }
  }
</script>

2. Register the Custom Element

Import GreenCheck and register <green-check> using the global customElements, where applicable:

import { GreenCheck } from '@vnphanquang/green-check';

// later where applicable
customElements.define('green-check', GreenCheck);

Optionally, you may find dynamically importing the module to be more efficient depending on your use case:

async function loadGreenCheck() {
  const { GreenCheck } = await import('@vnphanquang/green-check');
  customElements.define('green-check', GreenCheck);
}

// later
loadGreenCheck();

3. Using the Custom Element

Use <green-check> where applicable with the hostname attribute as the host name of your site. If not provided hostname will default to window.location.hostname, i.e current site.

<green-check hostname="www.yourdomain.xyz">
  <img
    src="https://cdn.jsdelivr.net/npm/@vnphanquang/green-check/dist/fallback.svg"
    width="200"
    height="95"
    alt="Fallback blank greencheck badge from The Green Web Foundation, in case JS is not (yet) available"
  />
</green-check>

Customizing Colors

Colors of the badge can be customized by providing the following CSS custom properties (default values are shown):

<green-check hostname="www.yourdomain.xyz">
  <!-- [...truncated fallback image...] -->
</green-check>

<style>
  green-check {
    --green-check-fg: #000;
    --green-check-bg: linear-gradient(45deg, #06ff06 4%, #dffcdd 24%, #fff 32%);
  }
</style>

This is helpful to ensure consistency with your site's color scheme or to support dark mode.

Development

Prerequisites

| Dependency | Installation | Description | | ---------- | --------------------------------------- | ------------------------------- | | node | recommended via volta | | | pnpm | follow guide on website | alternative to npm and yarn |

See [package.json] for preferred versions of node and pnpm. At project root, run:

Getting Started

This project is built with Vite. Start by installing dependencies

pnpm install

And run development server

pnpm dev

Todos

• [ ] Add tests