{"id":19924384,"url":"https://github.com/kontent-ai/custom-element-starter-react","last_synced_at":"2025-05-03T07:31:29.303Z","repository":{"id":63911149,"uuid":"558292071","full_name":"kontent-ai/custom-element-starter-react","owner":"kontent-ai","description":"Starter for Kontent.ai custom element written in React.","archived":false,"fork":false,"pushed_at":"2024-07-16T09:51:40.000Z","size":487,"stargazers_count":3,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-07T13:11:14.319Z","etag":null,"topics":["hacktoberfest","kontent-ai","kontent-ai-sample","kontent-ai-tool"],"latest_commit_sha":null,"homepage":"","language":"CSS","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/kontent-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-10-27T09:00:40.000Z","updated_at":"2025-01-30T16:50:58.000Z","dependencies_parsed_at":"2024-03-13T15:04:53.972Z","dependency_job_id":null,"html_url":"https://github.com/kontent-ai/custom-element-starter-react","commit_stats":null,"previous_names":["kontent-ai/custom-element-starter-react"],"tags_count":0,"template":true,"template_full_name":"kontent-ai/.github","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fcustom-element-starter-react","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fcustom-element-starter-react/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fcustom-element-starter-react/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fcustom-element-starter-react/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kontent-ai","download_url":"https://codeload.github.com/kontent-ai/custom-element-starter-react/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252156910,"owners_count":21703371,"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":["hacktoberfest","kontent-ai","kontent-ai-sample","kontent-ai-tool"],"created_at":"2024-11-12T22:17:13.217Z","updated_at":"2025-05-03T07:31:24.291Z","avatar_url":"https://github.com/kontent-ai.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![MIT License][license-shield]][license-url]\n\n[![Discord][discord-shield]][discord-url]\n\n\n# Kontent.ai React Custom Element Starter\n\nThis starter can be used to jumpstart your own custom element development with Kontent.ai. It contains all the necessary tools for creating a new [Custom Element](https://kontent.ai/learn/docs/custom-elements), a UI extension for content editors.\n\nYou can inspire yourself by browsing already created integrations [**here**](https://github.com/topics/kontent-ai-integration).\n\nIf you wish to include your integration into the mentioned list, please add the **kontent-ai-integration** topic into your github integration repository. \n\nAdditional Kontent.ai GitHub resources and tutorials can be found on [kontent-ai.github.io](https://kontent-ai.github.io/).\n\n# Getting Started\n\n## Running the project\n\nThe integration is created with [Vite](https://vitejs.dev/). \n\n1. Install dependencies with `npm ci`.\n2. Run a local development server with `npm run dev`.\n3. To deploy the element you can use the output of running `npm run build` command that you can find in the `dist` folder.\n\nSee [Vite guide](https://vitejs.dev/guide/#command-line-interface) for more available commands.\n\n## Define your Element's API\n\nThere are two main things that you'll need to define.\n* What configuration will your custom element need. (This is provided in the configuration when adding the custom element into a content type)\n* What value will the custom element save. In what format (the value needs to be serialized into string).\n\nYou can define the shape of your configuration in the `src/customElement/config.ts` file along with a validation function that will show the user an error when the provided configuration is not valid.\n\nIn the same way you can define the shape of your value in the `src/customElement/value.ts` file along with a parsing function from a string. Usually, the most flexible format is json serialized into the string.\n\n## Define your Element's height handling\n\nThe width of the custom element is always the full width of the editing element in the Kontent.ai app. However, the height can be defined by the element itself.\nIn the `src/main.tsx` file you can find the usage of the `CustomElementContext` where you can define the height of your element.\nIt can either be a specific size in pixels, `\"default\"` to use the default value or `\"dynamic\"` to resize the element based on the height of the element's body element.\n\n## Write your Element\n\nYou can start building the element in the `src/IntegrationApp.tsx` file where you can find example usage of several utilities defined in this repository that might come in useful.\n\n## Utilities in this repository\n\n### useConfig\n\nUse this hook to get the configuration provided for this custom element.\nThe configuration will be valid based on the validation function you defined in `src/customElement/config.ts` and will be of the `Config` type also defined in the file.\n\n### useValue\n\nUse this hook to get the current value of the element and a function to update the value.\nThe value will be parsed using the function defined in `src/customElement/value.ts` and will be of the `Value` type also defined in the file.\nExample:\n```ts\nconst [value, setValue] = useValue();\n```\n\n### useIsDisabled\n\nThis hook indicates whether your element should appear disabled. (e.g. when the item is published or the user doesn't have permission to modify the item)\nIt subscribes to changes so the returned value will always be up-to-date.\n\n### useEnvironmentId\n\nReturns the environment id of this element's content item.\n\n### useItemInfo\n\nGets information about the element's content item. \nSee the `ItemDetail` type in the `src/customElement/types/customElement.d.ts` file for details of available item information.\n\n### useVariantInfo\n\nGets the element's language id and codename.\n\n### useElements\n\nUse this hook to get values of the specified elements (accepts element codenames). \nThe hook subscribes to element changes so the returned values will always be up-to-date.\n\n### promptToSelectItems\n\nUse this function to prompt the user to select content items.\nYou can specify whether they should select only one or several.\nThe function returns details of the selected items.\n\n### promptToSelectAssets\n\nUse this function to prompt the user to select assets.\nYou can specify whether they should select only one or several and whether they should only select images or any asset.\nThe function returns details of the selected assets.\n\n# Structure of the Custom Element\n\n## Static resources in the `index.html` file\n\nEvery Kontent.ai custom element needs the [Custom Element API](https://kontent.ai/learn/reference/custom-elements-js-api/) to work properly.\nThis custom element is no exception and you can find it linked in the `index.html` template in the root of the repository.\n\nAdditionally, you can find there linked a CSS file from the `public` folder.\nThis contains Kontent.ai styling that you can leverage to make your custom element look similar to the rest of the Kontent.ai app.\nIt also includes Kontent.ai font.\n\n## `CustomElementContext`\n\nThis is the core of the connection to the Custom Element API.\nYou can find here the call to the `CustomElement.init` function that initializes the custom element and populates the React context with useful information like the element's value, config and so on.\nIt also handles handles height of the custom element using the supplied prop `height`.\n\n## `selectors.ts`\n\nHere you can find the implementation of most of the wrappers around the Custom Element API.\n\n# Contributing\n\nFor Contributing please see  [`CONTRIBUTING.md`](CONTRIBUTING.md) for more information.\n\n# License\n\nDistributed under the MIT License. See [`LICENSE.md`](./LICENSE.md) for more information.\n\n\n[contributors-shield]: https://img.shields.io/github/contributors/kontent-ai/custom-element-starter-react.svg?style=for-the-badge\n[contributors-url]: https://github.com/kontent-ai/custom-element-starter-react/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/kontent-ai/custom-element-starter-react.svg?style=for-the-badge\n[forks-url]: https://github.com/kontent-ai/custom-element-starter-react/network/members\n[stars-shield]: https://img.shields.io/github/stars/kontent-ai/custom-element-starter-react.svg?style=for-the-badge\n[stars-url]: https://github.com/kontent-ai/custom-element-starter-react/stargazers\n[issues-shield]: https://img.shields.io/github/issues/kontent-ai/custom-element-starter-react.svg?style=for-the-badge\n[issues-url]:https://github.com/kontent-ai/custom-element-starter-react/issues\n[license-shield]: https://img.shields.io/github/license/kontent-ai/custom-element-starter-react.svg?style=for-the-badge\n[license-url]:https://github.com/kontent-ai/custom-element-starter-react/blob/master/LICENSE.md\n[discord-shield]: https://img.shields.io/discord/821885171984891914?color=%237289DA\u0026label=Kontent.ai%20Discord\u0026logo=discord\u0026style=for-the-badge\n[discord-url]: https://discord.com/invite/SKCxwPtevJ\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkontent-ai%2Fcustom-element-starter-react","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkontent-ai%2Fcustom-element-starter-react","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkontent-ai%2Fcustom-element-starter-react/lists"}