{"id":14990332,"url":"https://github.com/nmetulev/wc-react","last_synced_at":"2025-04-12T02:10:24.192Z","repository":{"id":48529864,"uuid":"253137239","full_name":"nmetulev/wc-react","owner":"nmetulev","description":"React wrapper for web components","archived":false,"fork":false,"pushed_at":"2023-03-06T02:30:41.000Z","size":178,"stargazers_count":34,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-25T21:47:40.735Z","etag":null,"topics":["react","wc","web-component","web-components"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/nmetulev.png","metadata":{"files":{"readme":"readme.md","changelog":null,"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":"2020-04-05T02:06:16.000Z","updated_at":"2024-10-30T00:56:01.000Z","dependencies_parsed_at":"2024-06-18T18:20:46.616Z","dependency_job_id":"0b0e4a0e-3bc4-4bba-8999-0c3541b8ab12","html_url":"https://github.com/nmetulev/wc-react","commit_stats":{"total_commits":32,"total_committers":5,"mean_commits":6.4,"dds":0.59375,"last_synced_commit":"def79a6723084daee7ff02482c36d3cf7cc451e8"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmetulev%2Fwc-react","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmetulev%2Fwc-react/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmetulev%2Fwc-react/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmetulev%2Fwc-react/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nmetulev","download_url":"https://codeload.github.com/nmetulev/wc-react/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248473099,"owners_count":21109629,"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":["react","wc","web-component","web-components"],"created_at":"2024-09-24T14:19:54.334Z","updated_at":"2025-04-12T02:10:24.169Z","avatar_url":"https://github.com/nmetulev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React wrapper for web components\r\n\r\n[![npm](https://img.shields.io/npm/v/wc-react?style=for-the-badge)](https://www.npmjs.com/package/wc-react) ![GitHub](https://img.shields.io/github/license/nmetulev/wc-react?style=for-the-badge)\r\n\r\nUse `wc-react` to simplify usage of web components in React. This is a light wrapper to help manage events and props of the web component.\r\n\r\n```tsx\r\nconst MyComponent = wrapWc('my-web-component');\r\n```\r\n\r\nThe wrapper syncs props and events to the web component, including when they change and when the component is unmounted.\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install wc-react\r\n```\r\n\r\nor\r\n\r\n```bash\r\nyarn add wc-react\r\n```\r\n\r\n## Usage\r\n\r\nImport `wrapWc` at the top:\r\n\r\n```tsx\r\nimport {wrapWc} from 'wc-react';\r\n```\r\n\r\nCreate a new component that wraps your web component by calling the `wrapWc` function and pass the tag name of the web component.\r\n\r\n```tsx\r\nconst MyComponent = wrapWc('my-web-component');\r\n```\r\n\r\nYou can now use `MyComponent` anywhere in your JSX as if it were a regular React component. \r\n\r\nFor example, you can set the `someProp` property of the web component to an object:\r\n\r\n```jsx\r\nconst App = (props) =\u003e {\r\n\r\n  const someObj = {\r\n    prop1: 'bla'\r\n  }\r\n\r\n  return \u003cMyComponent someProp={someObj}\u003e\u003c/MyComponent\u003e;\r\n}\r\n```\r\n\r\nOr register event handlers:\r\n\r\n```jsx\r\nconst App = (props) =\u003e {\r\n\r\n  const handleEvent = (e) =\u003e {}\r\n\r\n  return \u003cMyComponent event={handleEvent}\u003e\u003c/MyComponent\u003e;\r\n}\r\n```\r\n\r\nAll properties and events map exactly as they are defined on the web component.\r\n\r\n\u003e Note: React events following the `onEvent` naming convention are also supported. For example, if you use the `onClick` event on the React component, wc-react will register the `click` event with the web component.\r\n\r\n## Refs\r\n\r\nWrapped components support passing a `ref` which will get a reference to the underlying web component.\r\n\r\nExample with `useRef`:\r\n\r\n```jsx\r\nconst App = (props) =\u003e {\r\n\r\n  let myRef = React.useRef();\r\n\r\n  const handleClick = () =\u003e {\r\n    console.log('web component reference', myRef.current)\r\n  }\r\n\r\n  return \u003cMyComponent ref={myRef} onClick={handleClick}\u003e\u003c/MyComponent\u003e;\r\n}\r\n```\r\n\r\nExample with callback:\r\n\r\n```jsx\r\nconst App = (props) =\u003e {\r\n\r\n  const onRefChanged = (element) =\u003e {\r\n    console.log('web component reference', element)\r\n  }\r\n\r\n  return \u003cMyComponent ref={onRefChanged}\u003e\u003c/MyComponent\u003e;\r\n}\r\n```\r\n\r\n## Typescript\r\n\r\n`wrapWc` supports optional props type to ensure type safety when using the component:\r\n\r\n```ts\r\ntype PersonProps = {\r\n  personDetails: PersonDetails, // object\r\n  showName: boolean,\r\n  personCardInteraction: PersonCardInteraction // enum\r\n}\r\n\r\nconst Person = wrapWc\u003cPersonProps\u003e('mgt-person');\r\n```\r\n\r\nBy default, if no type is provided, any prop will be valid.\r\n\r\n## Why\r\n\r\nIf you've used web components in React, you know that proper interop between web components and React components requires a bit of extra work.\r\n\r\nFrom [https://custom-elements-everywhere.com/](https://custom-elements-everywhere.com/):\r\n\r\n\u003e React passes all data to Custom Elements in the form of HTML attributes. For primitive data this is fine, but the system breaks down when passing rich data, like objects or arrays. In these instances you end up with stringified values like some-attr=\"[object Object]\" which can't actually be used.\r\n\r\n\u003e Because React implements its own synthetic event system, it cannot listen for DOM events coming from Custom Elements without the use of a workaround. Developers will need to reference their Custom Elements using a ref and manually attach event listeners with addEventListener. This makes working with Custom Elements cumbersome.\r\n\r\n\r\n## Example\r\n\r\nHere is an example of using the [`vaading-date-picker`](https://vaadin.com/components/vaadin-date-picker/) web component in React.\r\n\r\n### Without `wc-react`:\r\n\r\n```jsx\r\nimport React from 'react';\r\nimport '@vaadin/vaadin-date-picker';\r\n\r\nconst App: React.FunctionComponent = () =\u003e {\r\n\r\n  const handleChange = (e) =\u003e {/**/}\r\n  const localizedStrings = {/**/}\r\n\r\n  return \u003cvaadin-date-picker\r\n          label=\"When were you born?\"\r\n          ref={(element) =\u003e {\r\n            if (!element) {\r\n              return;\r\n            }\r\n\r\n            element.i18n = localizedStrings;\r\n\r\n            // the event listener needs to be removed\r\n            // when the element is unloaded - not shown here\r\n            element.addEventListener('change', (e) =\u003e handleChange(e));\r\n          }}\u003e\r\n          \u003c/vaadin-date-picker\u003e;\r\n};\r\n```\r\n\r\n### With `wc-react`:\r\n\r\n```jsx\r\nimport React from 'react';\r\nimport '@vaadin/vaadin-date-picker';\r\nimport { wrapWc } from 'wc-react';\r\n\r\nconst DatePicker = wrapWc('vaading-date-picker');\r\n\r\nconst App: React.FunctionComponent = () =\u003e {\r\n\r\n  const handleChange = (e) =\u003e {/**/}\r\n  const localizedStrings = {/**/}\r\n\r\n  return \u003cDatePicker \r\n            label=\"When were you born?\" \r\n            change={handleChange}\r\n            i18n={localizedStrings}\u003e\r\n          \u003c/DatePicker\u003e;\r\n};\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmetulev%2Fwc-react","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnmetulev%2Fwc-react","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmetulev%2Fwc-react/lists"}