Place components
A library of Web Components for tasks related to addresses and planning permission in the UK built with Lit, Vite, and Ordnance Survey APIs.
Web map
<my-map />
is an OpenLayers-powered map to support drawing and modifying red-line boundaries. Other supported modes include: highlighting an OS Feature that intersects with a given address point; clicking to select and merge multiple OS Features into a single boundary; and displaying static point or polygon data. Events are dispatched with the calculated area and geojson representation when you change your drawing.
Postcode search
<postcode-search />
is a GOV.UK-styled input that validates UK postcodes using these utility methods. When a postcode is validated, an event is dispatched containing the sanitized string.
Address autocomplete
<address-autocomplete />
fetches addresses in a given UK postcode using the OS Places API and displays them using GOV.UK's accessible-autocomplete component. An event is dispatched with the OS record when you select an address.
These web components can be used independently or together following GOV.UK's Address lookup design pattern.
Documentation & examples
- Interactive web component docs oslmap.netlify.app
- CodeSandbox (note: update the CDN script with a version number for new features)
Find these components in the wild, including what we're learning through public beta user-testing, at https://www.ripa.digital/.
Running locally
- Rename
.env.example
to.env.local
and replace the values - or simply provide your API keys as props - Install pnpm globally if you don't have it already
npm i pnpm -g
- Install dependencies
pnpm i
- Start development server
pnpm dev
Tests
Unit tests are written with Vitest, Happy Dom, and @testing-library/user-event. Each component has a main.test.ts
file.
-
pnpm test
startsvitest
in watch mode -
pnpm test:ui
opens Vitest's UI in the browser to interactively explore logs https://vitest.dev/guide/ui.html
Docs
We use Pitsby for documenting our web components. It's simple to configure (pitsby.config.js
plus a *.doc.js
per component), has good support for vanilla web components, and an interactive playground.
-
pnpm run docs
starts Pitsby in watch mode for local development -
pnpm run docsPublish
builds the site so Netlify can serve it frompitsby/
License
This repository is licensed under the Open Government License v3.