Embedded UI Components and this guide is currently in draft form and under active development. Components are not ready for production use and may change significantly until version 1.x.x is released. Please consider this document as a work in progress.
While we strive to incorporate ADA (Americans with Disabilities Act) best practices, please note that developers are responsible for conducting their own comprehensive ADA testing to ensure full compliance with all applicable standards and regulations.
Embedded UI Components offer a seamless way to integrate sophisticated UI components into your existing applications, providing a plug-and-play solution for Embedded Finance features. These components implement complex API capabilities for client onboarding and account linking, simplifying the integration process for developers.
All Embedded UI Components must be wrapped within the EBComponentsProvider
. The EBComponentsProvider
is specifically designed for these components and is not applicable to any other client components in your application.
The EBComponentsProvider
is a crucial wrapper component that must be placed at the top level of your Embedded UI Components implementation. It handles authentication, applies theming, and provides necessary context to all child Embedded UI Components.
It is usign @tanstack/react-query for handling API calls and authentication as well as Orval generated types for the API requests and responses.
-
apiBaseUrl
: The base URL for API calls (required) -
theme
: Customization options for the components' appearance (optional) -
headers
: Custom headers for API requests (optional)
import { EBComponentsProvider } from '@jpmorgan-payments/embedded-banking-components';
const EmbeddedFinanceSection = () => {
return (
<EBComponentsProvider
apiBaseUrl="https://your-api-base-url.com"
theme={{
colorScheme: 'light',
variables: {
primaryColor: '#007bff',
fontFamily: 'Arial, sans-serif',
}
}}
headers={{
'Custom-Header': 'value'
}}
>
{/* Your Embedded UI Components go here */}
</EBComponentsProvider>
);
};
The OnboardingWizard
component implements the client onboarding process as described in the Embedded Payments API documentation.
- Create a client profile
- Incremenrally update client's related parties
- Complete due diligence questions
- Handle client attestations
- Manage requests for additional documentation
- Check and display onboarding status
import { EBComponentsProvider, OnboardingWizard } from '@jpmorgan-payments/embedded-banking-components';
const OnboardingSection = () => {
const [clientId, setClientId] = useManageClientExternalState();
const handleClientCreation = ({ response, error }) => {
// Handle client creation response or error
setClientId(response.clientId);
};
const handleClientKYCInitiation = ({ response, error }) => {
// Handle KYC initiation response or error
};
return (
<EBComponentsProvider apiBaseUrl="https://your-api-base-url.com">
<OnboardingWizard
title="Client Onboarding"
clientId={clientId}
onClientCreation={handleClientCreation}
onClientKYCInitiation={handleClientKYCInitiation}
/>
</EBComponentsProvider>
);
};
OnboardingWizard could also accept products and jurisdictions as optional props to customize the onboarding process. Please refer to the OnboardingWizardProps interface in the codebase for more details.
The LinkedAccountWidget
component facilitates the process of adding a client's linked account, as described in the Add Linked Account API documentation.
- Add and manage external linked bank accounts for clients
- Handle complex micro-deposits initiation logic
import { EBComponentsProvider, LinkedAccountWidget } from '@jpmorgan-payments/embedded-banking-components';
const LinkedAccountSection = () => {
return (
<EBComponentsProvider apiBaseUrl="https://your-api-base-url.com">
<LinkedAccountWidget variant="default" />
</EBComponentsProvider>
);
};
Please refer to the LinkedAccountProps interface in the codebase for more details.
The EBComponentsProvider
accepts a theme
prop that allows for extensive customization of the components' appearance. The theme object can include the following properties:
-
colorScheme
: 'dark' | 'light' | 'system' -
variables
: An object containing various theme variables -
light
: Light theme-specific variables -
dark
: Dark theme-specific variables
Here's a table of available theme design tokens that can be used in the variables
, light
, and dark
properties:
Token Name | Description |
---|---|
fontFamily | Main font family for text |
backgroundColor | Background color of the main container |
foregroundColor | Main text color |
primaryColor | Primary brand color |
primaryColorHover | Hover state of primary color |
primaryForegroundColor | Text color on primary background |
secondaryColor | Secondary brand color |
secondaryForegroundColor | Text color on secondary background |
destructiveColor | Color for destructive actions |
destructiveForegroundColor | Text color on destructive background |
mutedColor | Color for muted elements |
mutedForegroundColor | Text color on muted background |
accentColor | Accent color for highlights |
accentForegroundColor | Text color on accent background |
cardColor | Background color for card elements |
cardForegroundColor | Text color for card elements |
popoverColor | Background color for popovers |
popoverForegroundColor | Text color for popovers |
borderRadius | Default border radius for elements |
buttonBorderRadius | Border radius specifically for buttons |
borderColor | Color for borders |
inputColor | Background color for input fields |
ringColor | Color for focus rings |
zIndexOverlay | z-index for overlay elements |
npm install @jpmorgan-payments/embedded-banking-components
or
yarn add @jpmorgan-payments/embedded-banking-components
- Prettier
- Tailwind CSS Intellisense
Use the files.associations
setting to tell VS Code to always open .css
files in Tailwind CSS mode:
"files.associations": {
"\*.css": "tailwindcss"
}
By default VS Code will not trigger completions when editing "string" content, for example within JSX attribute values. Updating the editor.quickSuggestions
setting may improve your experience:
"strings": "on"
}
- Create a new component in
./src/core
- Export it in
./src/index.tsx
- Also add it to
./src/vanilla/componentRegistry.ts
-
dev
– start development server -
build
– build production version of the app -
preview
– locally preview production build
-
typecheck
– checks TypeScript types -
lint
– runs ESLint -
prettier:check
– checks files with Prettier -
vitest
– runs vitest tests -
vitest:watch
– starts vitest watch -
test
– runsvitest
,prettier:check
,lint
andtypecheck
scripts
-
storybook
– starts storybook dev server -
storybook:build
– build production storybook bundle tostorybook-static
-
prettier:write
– formats all files with Prettier