{"id":24678316,"url":"https://github.com/firstclasspostcodes/firstclasspostcodes-js-plugin","last_synced_at":"2025-03-21T18:23:31.350Z","repository":{"id":54416825,"uuid":"229265663","full_name":"firstclasspostcodes/firstclasspostcodes-js-plugin","owner":"firstclasspostcodes","description":"🔌This simple to use plugin helps you to get started quickly, allowing you to add postcode lookup to any address form in minutes.","archived":false,"fork":false,"pushed_at":"2021-02-19T07:25:26.000Z","size":3023,"stargazers_count":0,"open_issues_count":14,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-17T22:56:26.623Z","etag":null,"topics":["javascript","svelte","umd"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/firstclasspostcodes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-12-20T12:59:58.000Z","updated_at":"2020-11-13T08:15:45.000Z","dependencies_parsed_at":"2022-08-13T15:00:49.908Z","dependency_job_id":null,"html_url":"https://github.com/firstclasspostcodes/firstclasspostcodes-js-plugin","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstclasspostcodes%2Ffirstclasspostcodes-js-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstclasspostcodes%2Ffirstclasspostcodes-js-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstclasspostcodes%2Ffirstclasspostcodes-js-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstclasspostcodes%2Ffirstclasspostcodes-js-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/firstclasspostcodes","download_url":"https://codeload.github.com/firstclasspostcodes/firstclasspostcodes-js-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244845395,"owners_count":20519954,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","svelte","umd"],"created_at":"2025-01-26T13:16:38.094Z","updated_at":"2025-03-21T18:23:31.325Z","avatar_url":"https://github.com/firstclasspostcodes.png","language":"JavaScript","readme":"[//]: # \"NOTE: The URL for the JS library is automatically updated by semantic-release.\"\n\n# Firstclasspostcodes\n![Build, test and release](https://github.com/firstclasspostcodes/firstclasspostcodes-js-plugin/workflows/Build,%20test%20and%20release/badge.svg) [![Cypress Dashboard](https://img.shields.io/badge/cypress-dashboard-brightgreen.svg)](https://dashboard.cypress.io/projects/hu4kvr/runs)\n\nOur browser plugin is compatible with all modern browsers and IE9+ _(polyfills required)_.\n\nThis simple to use plugin helps you to get started quickly, allowing you to add postcode lookup to any address form in minutes. \n\n\u003e **Note:** Are you looking for the [Svelte](https://svelte.dev) documentation? [See here](/NPM.md)\n\n## Documentation\nSee [@firstclasspostcodes/plugin](https://docs.firstclasspostcodes.com/js/plugin) for detailed usage, guides and examples.\n\n## Installation\nAdd the plugin directly into your HTML with:\n\n```html\n\u003cscript src=\"https://js.firstclasspostcodes.com/plugin/v2.3.1.js\"\u003e\u003c/script\u003e\n```\n\n**Note on older browsers:** You will need to use a polyfill service, the following example covers all of the required language features:\n\n```html\n\u003cscript src=\"https://polyfill.io/v3/polyfill.min.js?features=Promise%2Cfetch%2CObject.assign%2Cdefault\"\u003e\u003c/script\u003e\n```\n\n### Add the client library\nWe do not bundle the client library with the plugin, so you will need to add a separate script tag to require the JS client:\n\n```html\n\u003cscript src=\"https://js.firstclasspostcodes.com/v1.5.1.js\"\u003e\u003c/script\u003e\n```\n\nAll JS library versions are available on the [@firstclasspostcodes/js](https://github.com/firstclasspostcodes/firstclasspostcodes-js/releases) releases page.\n\n### Security\nWhere the libary is loaded on pages including sensitive information, we recommend using the [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) security feature. \n\nEvery version of the library is accompanied by an SRI hash file, the hash can be accessed directly using:\n\n```sh\n$ curl https://js.firstclasspostcodes.com/plugin/v2.3.1.sri.txt # =\u003e \"sha256-45tfd... sha384-43567ytr...\"\n```\n\nYou can then update the above `\u003cscript\u003e` tag, adding the integrity attribute:\n\n```html\n\u003cscript src=\"https://js.firstclasspostcodes.com/plugin/v2.3.1.js\"\n        integrity=\"sha256-45tfd... sha384-43567ytr...\"\n        crossorigin=\"anonymous\"\u003e\u003c/script\u003e\n```\n\n## Usage\nYou need to configure the plugin to use your API Key which is available on your [dashboard](https://dashboard.firstclasspostcodes.com/key). Below is a minimal working setup, you can see more guides on how to better customise the plugin by [viewing the documentation](https://docs.firstclasspostcodes.com/js/plugin).\n\n```html\n\u003cdiv id=\"postcode-lookup-form\"\u003e\u003c/div\u003e\n\u003cform\u003e\n  \u003cdiv\u003e\n    \u003clabel for=\"address-line-1\"\u003eAddress Line 1\u003c/label\u003e\n    \u003cinput name=\"address-line-1\" type=\"text\" data-address-line1 /\u003e\n  \u003c/div\u003e\n  \u003cdiv\u003e\n    \u003clabel for=\"address-line-2\"\u003eAddress Line 2\u003c/label\u003e\n    \u003cinput name=\"address-line-2\" type=\"text\" data-address-line2 /\u003e\n  \u003c/div\u003e\n  \u003cdiv\u003e\n    \u003clabel for=\"county\"\u003eCounty\u003c/label\u003e\n    \u003cinput name=\"county\" type=\"text\" data-address-locality /\u003e\n  \u003c/div\u003e\n  \u003cdiv\u003e\n    \u003clabel for=\"city\"\u003eCity\u003c/label\u003e\n    \u003cinput name=\"city\" type=\"text\" data-address-county /\u003e\n  \u003c/div\u003e\n  \u003cdiv\u003e\n    \u003clabel for=\"postcode\"\u003ePostcode\u003c/label\u003e\n    \u003cinput name=\"postcode\" type=\"text\" data-address-postcode /\u003e\n  \u003c/div\u003e\n\u003c/form\u003e\n\n\u003cscript\u003e\n  FirstclasspostcodesPlugin(\n    document.getElementById('postcode-lookup-form'), \n    {\n      apiKey: '111111111111',\n    },\n  );  \n\u003c/script\u003e\n```\n\n## Configuration\nThe plugin can be initialized with the same configuration overrides that you can supply for the [@firstclasspostcodes/js](https://github.com/firstclasspostcodes/firstclasspostcodes-js#configuration) library using the `apiOverrides` property (an example of its usage is below).\n\nIf you're running the [mock service](https://github.com/firstclasspostcodes/firstclasspostcodes-mock) docker container. You can configure the plugin to talk to it using the example below:\n\n```html\n\u003cscript\u003e\n  FirstclasspostcodesPlugin(\n    document.getElementById('postcode-lookup-form'), \n    {\n      apiKey: '111111111111', \n      apiOverrides: {\n        endpoint: 'http://localhost:2345',\n      }\n    }\n  );  \n\u003c/script\u003e\n```\n\n## Events\nWhilst not necessarily required, if you need to listen to events happening we support attaching event handlers for the following:\n\n| Event Name | Description |\n|:-------|:--------|\n| `address` | Fired when an address is selected from the drop down. Contains the address detail. |\n\nEvents are fired using the [CustomEvent](https://developer.mozilla.org/en/docs/Web/API/CustomEvent) class. Event properties are included inside the `.detail` property.\n\nEvent handlers can be attached using the following:\n\n```html\n\u003cscript\u003e\n  var plugin = FirstclasspostcodesPlugin(...);\n  \n  plugin.$on('address', (event) =\u003e {\n    console.log(event.detail);\n  });\n\u003c/script\u003e\n```\n\n## Plugin\nOur plugin is built using [Svelte](https://svelte.dev) and an instantiated component is returned from the `FirstclasspostcodesPlugin()` function. Therefore, the returned object is compatible with the documented [Client-side component API](https://svelte.dev/docs#Client-side_component_API).","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirstclasspostcodes%2Ffirstclasspostcodes-js-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirstclasspostcodes%2Ffirstclasspostcodes-js-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirstclasspostcodes%2Ffirstclasspostcodes-js-plugin/lists"}