{"id":15388252,"url":"https://github.com/georapbox/web-share-element","last_synced_at":"2025-04-15T20:21:05.793Z","repository":{"id":41066814,"uuid":"466717621","full_name":"georapbox/web-share-element","owner":"georapbox","description":"A custom element that implements the Web Share API to share user-defined data.","archived":false,"fork":false,"pushed_at":"2023-12-22T15:52:47.000Z","size":380,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-14T06:41:09.161Z","etag":null,"topics":["custom-elements","web-components"],"latest_commit_sha":null,"homepage":"https://georapbox.github.io/web-share-element/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/georapbox.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-06T11:31:03.000Z","updated_at":"2024-08-22T17:20:18.527Z","dependencies_parsed_at":"2023-12-20T15:28:24.315Z","dependency_job_id":"8fa432f2-89e1-4e68-9216-1b245e0dedb6","html_url":"https://github.com/georapbox/web-share-element","commit_stats":{"total_commits":55,"total_committers":2,"mean_commits":27.5,"dds":"0.018181818181818188","last_synced_commit":"0ba1db1dedfcc5e5a000f0d5c009df04341432ca"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georapbox%2Fweb-share-element","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georapbox%2Fweb-share-element/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georapbox%2Fweb-share-element/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georapbox%2Fweb-share-element/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/georapbox","download_url":"https://codeload.github.com/georapbox/web-share-element/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249145941,"owners_count":21220063,"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":["custom-elements","web-components"],"created_at":"2024-10-01T14:56:09.016Z","updated_at":"2025-04-15T20:21:05.769Z","avatar_url":"https://github.com/georapbox.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm version](https://img.shields.io/npm/v/@georapbox/web-share-element.svg)](https://www.npmjs.com/package/@georapbox/web-share-element)\n[![npm license](https://img.shields.io/npm/l/@georapbox/web-share-element.svg)](https://www.npmjs.com/package/@georapbox/web-share-element)\n\n[demo]: https://georapbox.github.io/web-share-element/\n[license]: https://github.com/georapbox/web-share-element/blob/main/LICENSE\n[changelog]: https://github.com/georapbox/web-share-element/blob/main/CHANGELOG.md\n\n# \u0026lt;web-share\u0026gt;\n\nA custom element that implements the [Web Share API](https://developer.mozilla.org/docs/Web/API/Navigator/share) to share user-defined data.\n\n[API documentation](#api) \u0026bull; [Demo][demo]\n\n## Install\n\n```sh\n$ npm install --save @georapbox/web-share-element\n```\n\n## Usage\n\n### Script\n\n```js\nimport { WebShare } from './node_modules/@georapbox/web-share-element/dist/web-share.js';\n\n// Manually define the element.\nWebShare.defineCustomElement();\n```\n\nAlternatively, you can import the automatically defined custom element.\n\n```js\nimport './node_modules/@georapbox/web-share-element/dist/web-share-defined.js';\n```\n\n### Markup\n\n```html\n\u003cweb-share \n  share-url=\"https://developer.mozilla.org\" \n  share-title=\"MDN\" \n  share-text=\"Learn web development on MDN!\"\n\u003e\u003c/web-share\u003e\n```\n\n### Style\n\nBy default, the component is style-free to remain as less opinionated as possible. However, you can style the various elements of the component using [CSS Parts](#css-parts) provided for this purpose.\n\n## API\n\n### Properties\n| Name | Reflects | Type | Required | Default | Description |\n| ---- | -------- | ---- | -------- | ------- | ----------- |\n| `shareUrl`\u003cbr\u003e*`share-url`* | ✓ | String | - | `''` | A string representing a URL to be shared. |\n| `shareTitle`\u003cbr\u003e*`share-title`* | ✓ | String | - | `''` | A string representing a title to be shared. |\n| `shareText`\u003cbr\u003e*`share-text`* | ✓ | String | - | `''` | A string representing text to be shared. |\n| `shareFiles` | - | Array | - | `[]` | An array of [File](https://developer.mozilla.org/docs/Web/API/File) objects representing files to be shared. this property will be omitted if the device does not support sharing files or a file type is not shareable and it will try to share the rest of the properties. Check [here](https://developer.mozilla.org/docs/Web/API/Navigator/share#shareable_file_types) for shareable file types. |\n| `disabled` | ✓ | Boolean | - | `false` | Determines if the share button is disabled. |\n\n### Slots\n\n| Name | Description |\n| ---- | ----------- |\n| `button` | Override the share button with another element of your preference. Example: `\u003ca href=\"#\" slot=\"button\" role=\"button\"\u003eShare this page\u003c/a\u003e` |\n| `button-content` | Override the share button's content with content of your preference. Useful if all you need is to change the button's label. Example: `\u003cspan slot=\"button-content\"\u003eShare this page\u003c/span\u003e` |\n\n### CSS Parts\n\n| Name | Description |\n| ---- | ----------- |\n| `button` | The share button. |\n| `button--disabled` | The share button when is disabled. |\n\n### Methods\n\n| Name | Type | Description | Arguments |\n| ---- | ---- | ----------- | --------- |\n| `defineCustomElement` | Static | Defines/registers the custom element with the name provided. If no name is provided, the default name is used. The method checks if the element is already defined, hence will skip trying to redefine it. | `elementName='web-share'` |\n| `share`\u003csup\u003e1\u003c/sup\u003e | Instance | Shares the shareable data taken from the element's properties. | - |\n\n\u003csup\u003e1\u003c/sup\u003e Instance methods are only available after the component has been defined. To ensure that the component has been defined, you can use the `whenDefined` method of the `CustomElementRegistry` interface. For example:\n\n```js\ncustomElements.whenDefined('web-share').then(() =\u003e {\n  /* call methods here */\n});\n```\n\n### Events\n\n| Name | Description | Event Detail |\n| ---- | ----------- | ------------ |\n| `web-share:success` | Emitted when share is successful. | `{ shareData: { url?: String, title?: String, text?: String, files?: File[] } }` |\n| `web-share:abort` | Emitted when share is aborted. | `{ error: AbortError }` |\n| `web-share:error` | Emitted when share fails for any reason. Here is a [full list of possible exceptions](https://developer.mozilla.org/docs/Web/API/Navigator/share#exceptions). | `{ error: TypeError }` |\n\n## Utilities\n\n```js\nisWebShareSupported()\n```\n\nReturns `true` if Web Share API is supported by the platform, otherwise returns `false`. By default, it checks if `navigator.share` is supported. If you want to check for support of a specific shareable data type, you can pass an object as argument with the shareable data you want to check for support. For example, if you want to check if sharing files is supported, you can pass `{files: [File, ...]}` as argument. Available shareable data types are `url`, `text`, `title` and `files`.\n\n```js\nisWebShareSupported({ \n  files: [new File(['foo'], 'foo.txt', { type: 'text/plain', })]\n});\n```\n\n\u003e NOTE: You don't necessarily need to check for Web Share API support. The component handles errors regarding support internally; you can catch them by registering the `web-share:error` event. The utility might come handy for a scenario that you want to dynamically import the custom element only if the API is supported (check example below). In cases that the Web Share API is partially supported, (eg Firefox in Android supports sharing `url` and `title` but not `text` or `files`), the component will try to share the other shareable data if provided and will omit any unsupported shareable data.\n\n```js\nimport { isWebShareSupported } from './node_modules/@georapbox/web-share-element/dist/is-web-share-supported.js';\n\n// Check if Web Share API is supported\nif (isWebShareSupported()) {\n  // Import component dynamically...\n  const { WebShare } = await import('./node_modules/@georapbox/web-share-element/dist/web-share.js');\n\n  WebShare.defineCustomElement();\n}\n```\n\n## Changelog\n\nFor API updates and breaking changes, check the [CHANGELOG][changelog].\n\n## Development setup\n\n### Prerequisites\n\nThe project requires `Node.js` and `npm` to be installed on your environment. Preferrably, use [nvm](https://github.com/nvm-sh/nvm) Node Version Manager and use the version of Node.js specified in the `.nvmrc` file by running `nvm use`.\n\n### Install dependencies\n\nInstall the project dependencies by running the following command.\n\n```sh\nnpm install\n```\n\n### Build for development\n\nWatch for changes and start a development server by running the following command.\n\n```sh\nnpm start\n```\n\n### Linting\n\nLint the code by running the following command.\n\n```sh\nnpm run lint\n```\n\n### Testing\n\nRun the tests by running any of the following commands.\n\n```sh\nnpm test\nnpm run test:watch # watch mode\n```\n\n### Build for production\n\nCreate a production build by running the following command.\n\n```sh\nnpm run build\n```\n\n## License\n\n[The MIT License (MIT)][license]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorapbox%2Fweb-share-element","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeorapbox%2Fweb-share-element","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorapbox%2Fweb-share-element/lists"}