React Native Embedding
Komo cards can be embedded into your React Native application through Komo’s NPM package @komo-tech/react-native-widgets .
Installation
npm install @komo-tech/react-native-widgets
NOTE: @komo-tech/react-native-widgets has a peer dependency on react-native-webview , and recommends the latest major version, 13.x
.
Basic Usage
- The quickest way to get started with embedding Komo content in react native is by using the
KomoCardWidget
component. - This component combines metadata fetching, card cover display, and modal handling for the card experience.
- The only required prop is
embedMetaUrl
. To find this in the Komo portal:- Navigate to the settings of the card to be embedded.
- Select the
Embed
tab and click onReact Native code
in the right sidebar. - Copy the
Card embed meta URL
and use it as the value of theembedMetaUrl
prop.
import { KomoCardWidget } from '@komo-tech/react-native-widgets';
// ...
<KomoCardWidget
embedMetaUrl={KomoCardNativeEmbedUrl}
containerStyle={{ maxWidth: '80%' }}
/>;
Prefilling form details
- You can pass information through to the Komo experience that will be pre-filled in any forms that the user may encounter.
- Pass a plain
Record<string,string>
object of keys and values through to theformPrefillValues
prop onKomoCardWidget
orExperienceModal
. - The object keys must match the Unique ID of the form field or contact property from the Komo Platform that you want to prefill.
<KomoCardWidget
embedMetaUrl={KomoCardNativeEmbedUrl}
containerStyle={{ maxWidth: '80%' }}
formPrefillValues={{
email: 'email@domain.com',
first_name: 'Person',
last_name: 'Doe',
}}
/>;
Advanced usage
Metadata fetching
- The first step to using embedded Komo content involves fetching the card metadata.
- Use the
useFetchCardMetadata
hook and theNative embed URL
copied from the platform to fetch the CardEmbedMetadata. - The CardEmbedMetadata has the information required to render the cover image (
imageUrl
) and the URL (embedUrl
) that the ExperienceModal needs to render the embedded experience. - Note: you can use your own data-fetching patterns if you require more advanced data fetching handling. So long as it produces a CardEmbedMetadata, you can pass that to the other components that you want to use.
import { useFetchCardMetadata } from '@komo-tech/react-native-widgets';
// ... rest of your component
const {data, isLoading, isError} = useFetchCardMetadata({embedMetaUrl: KomoCardNativeEmbedUrl});
// ... use the data.
Render a Card Cover
- The
CardCover
component is used to display the cover image of a Komo card. - It handles loading states, error states, and button display.
- The component requires an
onClick
handler andisLoading
state. - The
imageUrl
andimageAspectRatio
props are typically obtained from the CardEmbedMetadata.
import { CardCover } from '@komo-tech/react-native-widgets';
// ... rest of your component
<CardCover
imageUrl={metadata?.imageUrl}
imageAspectRatio={metadata?.imageAspectRatio}
isLoading={isLoading}
isError={isError}
onClick={() => doSomethingOnCoverClicked()}
metaButtonStyle={metadata?.buttonStyle}
containerStyle={{ borderRadius: 8 }}
/>
Using the Experience Modal
- The
ExperienceModal
component is used to display the full Komo experience in a modal overlay. - It handles loading states, error states, and communication with the embedded experience.
- The component requires an
isOpen
state andonClose
handler. - A valid
embedUrl
prop is required for the experience modal to function, and this is typically obtained from the CardEmbedMetadata.
import { ExperienceModal } from '@komo-tech/react-native-widgets';
// ... rest of your component
<ExperienceModal
isOpen={isModalOpen}
onClose={() => setIsModalOpen(false)}
embedUrl={metadata?.embedUrl}
loadingTimeoutMs={15000} // Optional: customize loading timeout
appId="my-app" // Optional: identify where the content is embedded
/>
Experience Modal example without Card Cover
- You can use whichever components you want to build your desired experience.
- For example, you can trigger the
ExperienceModal
without rendering our CardCover.
// ... rest of your component
const { data, isLoading } = useFetchCardMetadata({
isEnabled,
embedMetaUrl: EmbedMetaUrlFromKomoPortal,
});
const [modalOpen, setModalOpen] = useState(false);
// other code, e.g. some element that calls setModalOpen(true) after isLoading returns false
<ExperienceModal
isOpen={modalOpen}
onClose={() => {
setModalOpen(false);
}}
embedUrl={data?.embedUrl}
/>
API Reference
KomoCardWidget Props
Name | Type | Description | Optional |
---|---|---|---|
embedMetaUrl | String | The native embed url taken from the Komo portal settings of the card to be embedded | False |
appId | String | Useful for the embedded Komo content to identify where it's being embedded | True |
containerStyle | StyleProp<ViewStyle> | Style overrides for the container of the card cover (including both image and CTA button) | True |
coverImageStyle | StyleProp<ImageStyle> | Style overrides for the image of the card cover | True |
buttonStyle | StyleProp<ViewStyle> | Style overrides for the CTA button of the card cover | True |
buttonTextStyle | StyleProp<TextStyle> | Style overrides for the CTA button text of the card cover | True |
coverLoader | ReactNode | The loader shown while the cover is loading (defaults to a skeleton card loader) | True |
coverErrorDisplay | ReactNode | Override the default error display for the cover | True |
hideCoverButton | Boolean | Hide the CTA button of the cover | True |
modalHeader | ReactNode | The header of the modal to render instead of the default | True |
onError | (error) => void | Callback for when an error occurs during querying the embed metadata endpoint | True |
onModalClose | () => void | Callback on modal close | True |
onModalOpen | () => void | Callback on modal open | True |
shareClickUrl | String | Override of the url that redirects a user when clicking on a share link | True |
formPrefillValues | Record<string, string> | Prefill values for the form within the experience | True |
onFileDownload | WebViewProps["onFileDownload"] | Callback for when a file download is requested. Only applies to iOS. See react-native-webview docs for more details | True |
CardEmbedMetadata
Name | Type | Description | Optional |
---|---|---|---|
title | string? | The title of the card | True |
imageUrl | string? | URL of the card's cover image | True |
imageHeight | number? | Height of the cover image in pixels | True |
imageWidth | number? | Width of the cover image in pixels | True |
imageAspectRatio | number? | Aspect ratio of the cover image | True |
embedUrl | string? | URL for the embedded experience | True |
buttonStyle | ButtonStyle? | Styling for the card's button | True |
ButtonStyle
Name | Type | Description | Optional |
---|---|---|---|
text | string? | Text to display on the button | True |
backgroundColor | string? | Background color of the button | True |
color | string? | Text color of the button | True |
useFetchCardMetadata Hook
Options
Name | Type | Description | Optional |
---|---|---|---|
embedMetaUrl | string | The URL of the embed metadata for the card, copied from the Komo Portal | False |
isEnabled | boolean | Whether the embed metadata query is enabled. Defaults to true | True |
onError | (e: any) => void | Callback for when an error occurs during querying the embed metadata endpoint | True |
Result
Name | Type | Description | Optional |
---|---|---|---|
data | CardEmbedMetadata? | The embed metadata for the card | True |
isLoading | boolean | Whether the embed metadata is loading | False |
isError | boolean | Whether the embed metadata query failed | False |
isSuccess | boolean | Whether the embed metadata query succeeded | False |
refetchAsync | () => Promise<void> | Function to refetch the embed metadata | False |
CardCover Props
Name | Type | Description | Optional |
---|---|---|---|
onClick | () => void | The callback for when the cover is clicked | False |
isLoading | boolean | Whether the cover is loading | False |
isError | boolean? | Whether the cover is in an error state | True |
loader | ReactNode? | Override the default skeleton loader | True |
errorDisplay | ReactNode? | Override the default error display | True |
metaButtonStyle | ButtonStyle? | The button style returned from the embed metadata endpoint | True |
overrideButtonStyle | StyleProp<ViewStyle>? | Override the button style | True |
overrideButtonTextStyle | StyleProp<TextStyle>? | Override the button text style | True |
containerStyle | StyleProp<ViewStyle>? | Override the container style | True |
coverImageStyle | StyleProp<ImageStyle>? | Override the cover image style | True |
hideCoverButton | boolean? | Whether to hide the cover button | True |
imageUrl | string? | The url of the cover image | True |
imageAspectRatio | number? | The aspect ratio of the cover image | True |
ExperienceModal Props
Name | Type | Description | Optional |
---|---|---|---|
isOpen | boolean | Whether the modal is open | False |
onClose | () => void | Callback for when close is requested | False |
embedUrl | string | The URL of the embedded card experience | False |
modalHeader | ReactNode | Override the default modal header | True |
shareClickUrl | string | Override the url that redirects a user when clicking on a share link | True |
appId | string | An identifier for the embedded Komo content | True |
formPrefillValues | Record<string, string> | Prefill values for the form within the experience | True |
loadingIndicator | ReactNode | Override the default loading indicator | True |
modalProps | ModalProps | Override the default modal props | True |
loadingTimeoutMs | number | Timeout in milliseconds before showing error state. Defaults to 15000ms | True |
errorDisplay | ({ onRetry }: { onRetry: () => void }) => ReactNode | Override the default error display | True |
onFileDownload | WebViewProps["onFileDownload"] | Callback for when a file download is requested. Only applies to iOS. See react-native-webview docs for more details | True |