Skip to Content
Embed SDKReact Native

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 on React Native code in the right sidebar.
    • Copy the Card embed meta URL and use it as the value of the embedMetaUrl 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 the formPrefillValues prop on KomoCardWidget or ExperienceModal.
  • 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 the Native 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 and isLoading state.
  • The imageUrl and imageAspectRatio 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 and onClose 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

NameTypeDescriptionOptional
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

NameTypeDescriptionOptional
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

NameTypeDescriptionOptional
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

NameTypeDescriptionOptional
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

NameTypeDescriptionOptional
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

NameTypeDescriptionOptional
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

NameTypeDescriptionOptional
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