{"id":17023908,"url":"https://github.com/maxart2501/share-this","last_synced_at":"2025-05-15T18:11:25.603Z","repository":{"id":40336182,"uuid":"76811370","full_name":"MaxArt2501/share-this","owner":"MaxArt2501","description":"Medium-like text selection sharing without dependencies","archived":false,"fork":false,"pushed_at":"2023-01-04T21:49:57.000Z","size":2022,"stargazers_count":809,"open_issues_count":19,"forks_count":54,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-05-13T04:07:05.734Z","etag":null,"topics":["medium","popover","selection","sharing"],"latest_commit_sha":null,"homepage":"https://maxart2501.github.io/share-this/","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/MaxArt2501.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-18T22:50:13.000Z","updated_at":"2025-02-24T15:43:25.000Z","dependencies_parsed_at":"2023-02-02T21:15:27.880Z","dependency_job_id":null,"html_url":"https://github.com/MaxArt2501/share-this","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxArt2501%2Fshare-this","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxArt2501%2Fshare-this/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxArt2501%2Fshare-this/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxArt2501%2Fshare-this/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MaxArt2501","download_url":"https://codeload.github.com/MaxArt2501/share-this/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254394726,"owners_count":22063984,"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":["medium","popover","selection","sharing"],"created_at":"2024-10-14T07:14:41.709Z","updated_at":"2025-05-15T18:11:25.586Z","avatar_url":"https://github.com/MaxArt2501.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"share-this\n==========\n\nMedium-like text selection sharing without dependencies\n\n[![Version](http://img.shields.io/npm/v/share-this.svg)](https://www.npmjs.org/package/share-this)\n[![Build Status](https://travis-ci.org/MaxArt2501/share-this.svg?branch=master)](https://travis-ci.org/MaxArt2501/share-this)\n[![License Type](https://img.shields.io/github/license/MaxArt2501/share-this.svg)](https://img.shields.io/github/license/MaxArt2501/share-this.svg)\n\n![share-this in action](https://maxart2501.github.io/share-this/example.gif)\n\n## Purpose\n\nThis lightweight library allows to create a simple interface to share selected text in a page, in the form of a small popover over the selected portion of text.\n\nFeatures:\n\n* customizable sharing channels (\"sharers\")\n* restriction on selected elements\n* customizable CSS classes and stylesheets\n* hooks on opening and closing the popover, and on sharing action\n\nAll in a tiny library (less than 1.8 KB minified and gzipped, plus less than 0.5 KB for the optional provided style sheet and 0.5-1.3 KB for the sample sharers).\n\n## Installation\n\nVia npm:\n\n```bash\n$ npm install --save share-this\n```\n\nVia bower:\n\n```bash\n$ bower install share-this\n```\n\nVia CDN:\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/share-this/dist/share-this.js\"\u003e\u003c/script\u003e\n```\n\n\n## Usage\n\nThe library is in UMD format, so feel free to use the module loader of your choice:\n\n```javascript\n// CommonJS\nconst shareThis = require(\"share-this\");\n\n// ES6\nimport shareThis from \"share-this\";\n\n// AMD\ndefine([ \"share-this\" ], shareThis =\u003e {\n    // ...\n});\n\n// Global\nvar shareThis = window.ShareThis;\n```\n\n`shareThis` is a factory for text selection sharing functionality:\n\n```javascript\nconst selectionShare = shareThis({\n    selector: \"#shareable\",\n    sharers: mySharerList\n});\n\nselectionShare.init();\n```\n\nThese are the options for the factory:\n\n* `document`: the `Document` object to apply the sharing functionality (default: `document`);\n* `popoverClass`: the class name (or names) to be used in the root element of the popover (default: `share-this-popover`);\n* `selector`: restricts the shared text to the contents of the elements matching `selector` (default: `\"body\"`);\n* `sharers`: an array of sharing channels (Twitter, Facebook, email...); see later for details;\n* `shareUrl`: a reference URL for the shared text (default: the `location` object of the `document` property);\n* `transformer`: a function that transforms the extracted selected text (default: a function that trims and collapses whitespaces);\n* `onOpen`: a function that gets called when the sharing popover is opened. The popover's element, the transformed selected text and its original version are passed as arguments;\n* `onClose`: a function that gets called when the sharing popover is closed.\n\nWhen you're done sharing text, you can call the `destroy` method;\n\n```javascript\nselectionShare.destroy();\n```\n\nA destroyed sharing object can *not* be `init`ialized again.\n\nIf a layout change in the page moves the selected text from its original position, it might happen that the relative popover is\nnot aligned to it anymore. If that happens, call the instance's `reposition` method:\n\n```javascript\nif (selectionShare.reposition()) {\n    console.log('Popover correctly realigned');\n}\n```\n\n\n\n## Sharers\n\nA \"sharer\" is simply an object with just one mandatory method: `render`, that must return the HTML string of the sharing button;\nand a `name` property.\n\n### `render(text: string, rawText: string, shareUrl: string) =\u003e string` (mandatory)\n\nThis function receives these arguments:\n\n* `text`: the text that should be shared;\n* `rawText`: the original selected text content (i.e., not mangled by the `transformer`);\n* `shareUrl`: the reference URL to be shared (see the options).\n\nIt must return the HTML of the button/link/element that should provide the required sharing functionality.\n\n### `name: string` (mandatory)\n\nA unique string (among the sharers) that identifies the sharer (e.g.: `\"twitter\"`, `\"facebook\"`, ...).\n\n### `active(text: string, rawText: string): any | boolean` (optional)\n\nThis property could actually be a function (with the above signature) or a boolean, stating if the sharer is enabled (`true`) or not.\nIf it's a function, it should return a truthy or falsy value, with the same meaning.\n\n### `action(event: MouseEvent, item: HTMLLIElement): void` (optional)\n\nA function to be called when the user clicks/taps on the sharing button. The `event`'s default is *not* prevented. `item` is the\n`\u003cli\u003e` element that wraps the sharer's button.\n\n\n## Using the sharers\n\nThis library provides some default sharers, that could be loaded like this:\n\n```javascript\n// CommonJS\nconst twitterSharer = require(\"share-this/dist/sharers/twitter\");\n\n// ES6\nimport * as twitterSharer from \"share-this/dist/sharers/twitter\";\n\n// AMD\ndefine([ \"share-this/dist/sharers/twitter\" ], twitterSharer =\u003e {\n    // ...\n});\n\n// Global\nconst twitterSharer = window.ShareThisViaTwitter;\n```\n\nThen you can use the sharers of your choice:\n\n```javascript\nconst selectionShare = shareThis({\n    sharers: [ twitterSharer ]\n});\n```\n\nNote: the `sharers` array should *not* be empty, or nothing will ever happen.\n\nThe list of the sharers is also available on the `sharers` property on the popover element (e.g. passed to the `onOpen` callback), for dynamic\nruntime handling.\n\nThe following are the default basic sharers provided by the package:\n\nSite     | File location               | Name        | Global variable\n---------|-----------------------------|-------------|-----------------------\nTwitter  | `dist/sharers/twitter.js`   | `twitter`   | `ShareThisViaTwitter`\nFacebook | `dist/sharers/facebook.js`  | `facebook`  | `ShareThisViaFacebook`\nReddit   | `dist/sharers/reddit.js`    | `reddit`    | `ShareThisViaReddit`\nEmail    | `dist/sharers/email.js`     | `email`     | `ShareThisViaEmail`\nLinkedIn (*see note below!) | `dist/sharers/linked-in.js`     | `linked-in`     | `ShareThisViaLinkedIn`\n\nYou can find a couple more on the [presentation page](https://maxart2501.github.io/share-this/) of the library.\n\n**Note about the LinkedIn sharer**: LinkedIn doesn't allow sharing a site with a custom title/snippet of text. Therefore ShareThis would fail\nto bring any value relatively to other sharing methods. The sharer is kept for backwards compatibility only. The following warning will appear\nin the console the first time the sharer is rendered:\n\n\u003e LinkedIn doesn't allow sharing links with custom titles anymore, so the main point of ShareThis\n\u003e (sharing a portion of text) couldn't be accomplished. You're encouraged to share your URLs with other,\n\u003e more conventional means, like the official LinkedIn share plugin. See\n\u003e https://docs.microsoft.com/en-us/linkedin/consumer/integrations/self-serve/plugins/share-plugin\n\n\n## Developer friendly\n\nThis library's source code (that can be found in the [src](src/) folder) uses ES2015 profusely, including ES2015 module definition and loading.\nThis means that, at the moment, its modules can't be `require`d without prior transpilation, but this also mean that this library is directly\nusable in environments that support ES2015 modules.\n\nThe `\"module\"` property is defined in [package.json](package.json) for those module loaders that support it\n([Rollup](https://github.com/rollup/rollup), for example, which is also used to bundle the library).\n\nSource files for style sheets are also provided in both [LESS](style/less) and [SCSS](style/scss) form.\n\n\n## Browser support\n\n* Chrome/Opera\n* Firefox 52+ (1)\n* Edge\n* Safari 5.1+\n* Internet Explorer 9+\n\nNotes:\n\n1. Firefox below v52 lacks support of the [`selectionchange` event](https://developer.mozilla.org/en-US/docs/Web/Events/selectionchange).\n\n\n## Mobile devices\n\nOn mobile browsers, you might not want to have `share-this` to interfere with native sharing features, so you might want it disabled. In order\nto it, you might want to do something like this:\n\n```js\nif (!window.matchMedia\n        || !window.matchMedia(\"(pointer: coarse)\").matches) {\n    selectionShare.init();\n}\n```\n\n(The rationale of this is that the device's primary pointer is \"coarse\" - that includes touch devices, but also Kinect and WiiMotes - then the\ndevice *probably* features a native sharing interface. See [CanIUse](http://caniuse.com/#feat=css-media-interaction) for details about Interaction\nMedia Features. If the browser doesn't support `window.matchMedia` altogether, then it's *probably* a PC with a mouse/trackpad, so it's fine to\ninitialize `share-this`.)\n\nKeep in mind that native sharing features let the *device* do the job, using apps or services installed on it, `share-this` keep this task on the\npage, which means it could offer \"sharing\" capabilities that the device may not have (e.g.: \"save to my account's notes\" or \"pronounce this using\nvoice synthesis\"), so you might want to show *both* native and custom sharing interfaces.\n\n\n## To do\n\n* Name change ([issue](https://github.com/MaxArt2501/share-this/issues/38))\n* More test coverage\n* Support for JSX in sharers' `render` method\n* Move the sharers from the library to separate packages ([issue](https://github.com/MaxArt2501/share-this/issues/39))\n\n\n## License\n\nMIT @ Massimo Artizzu 2016-2019. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxart2501%2Fshare-this","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxart2501%2Fshare-this","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxart2501%2Fshare-this/lists"}