brokerize elements
is the official UI elements library for the brokerize API. Together with @brokerize/client
it provides drop-in brokerage UI elements for various trading use cases.
The brokerize client libraries are publicly available, so you can just install them like any other npm package:
Once you have the token, this is how you add it to a project:
$ npm init -y
$ npm install @brokerize/elements
To use brokerize elements, an instance of brokerize client must be created first. This is used by the the UI elements to interact with the API.
import { Brokerize } from '@brokerize/client';
const brokerizeClient = new Brokerize({
// API configuration
basePath: BROKERIZE_API_URL /* https://api-preview.brokerize.com for our preview environment */,
clientId: '<YOUR-API-CLIENT-ID>',
cognito: {
Endpoint: '<PROVIDED-COGNITO-ENDPOINT>',
ClientId: '<PROVIDED-COGNITO-CLIENT-ID>',
UserPoolId: '<PROVIDED-COGNITO-USERPOOL-ID>'
},
// provide global dependencies
fetch: globalThis.fetch.bind(globalThis),
createAbortController: () => new AbortController(),
createWebSocket: (url, protocol) => new WebSocket(url, protocol)
});
Property | Description | optional |
---|---|---|
basePath | The API base path | ❌ |
clientId | Your Client ID for the brokerize API | ❌ |
cognito | Configuration for logging in brokerize users (not relevant for most clients) | ✅ |
fetch | Optional custom implementation of fetch
|
✅ |
createAbortController | Optional create function (should return an instance of AbortController that is compatible with the provided fetch ) |
✅ |
createWebSocket | Optional create function for WebSockets | ✅ |
In order to use the UI elements, a theme
should be configured (if no theme is defined, a default theme will be used). You can use the brokerize theme designer to build a theme JSON.
const theme = {
layout: 'columns',
logoStyle: 'light',
tokens: {
'zl-primary-color': 'red',
'zl-primary-bg-color': 'white',
'zl-secondary-bg-color': 'var(--zl-color-gray-lighter)',
'zl-outline-color': 'var(--zl-color-primary-light)',
'zl-default-text-color': 'var(--zl-color-gray-darkest)',
'zl-secondary-text-color': 'var(--zl-color-gray-darkest)',
'zl-placeholder-text-color': 'var(--zl-color-gray-darker)',
'zl-success-color': '#3db969',
'zl-error-color': '#ff3e3e',
'zl-buy-color': 'var(--zl-success-color)',
'zl-sell-color': 'var(--zl-error-color)',
'zl-app-font-size': 'var(--zl-font-size-sm, 1rem)',
'zl-input-bg-color': 'var(--zl-primary-bg-color)',
'zl-input-border-color': 'var(--zl-default-border-color)',
'zl-notification-info-color': 'var(--zl-color-gray-darkest)',
'zl-notification-info-color': 'var(--zl-color-gray-darkest)',
'zl-notification-bg-color': 'var(--zl-color-lightest)',
'zl-form-item-gap': 'var(--zl-spacing-02) var(--zl-spacing-03)',
'zl-form-item-error-border-width': '0px'
};
instead of using the create-methods, all components are also offered as standard web-components. Using them is as simple as
<brokerize-main [apiCtx]="apiCtx" [theme]="theme" />
where the context is retrieved from the client
const apiCtx = await this.client.createAuthorizedContext(authCtxCfg);
and a theme can be provided in the same manner as in the theming section. The above code is valid for Angular (and it's way of binding properties). Most frameworks allow to integrate custom elements similarly.
A view that lets the user pick a broker for logging in. Selection of the broker as well as showing / accepting the terms and conditions of the given broker is handled inside the component.
It calls the onLogin
callback when the user has accepted the terms and conditions and clicked on Login
:
createBrokerList({
authorizedApiContext,
theme,
addFrame,
renderTo,
onLogin({ brokerName }) {
// show the login process for broker `brokerName` here
},
openExternalLink
});
<brokerize-broker-list ... />
Property | Description | optional |
---|---|---|
client | Instance of the @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |
addFrame | Add a "powered by brokerize" frame to the component | ✅ |
supportLink | Add a support link to the brokerize frame config, e.g. { emailSubject: 'Help needed for trading in XYZ app'}
|
✅ |
confirmationStorage | An implementation of a ConfirmationStorage which stores whether users have accepted legal terms. By default, this will try to use the LocalStorage
|
✅ |
event | Description |
---|---|
login | is fired when the user has accepted the terms and conditions and clicked on Login
|
createBrokerLoginForm({
authorizedApiContext,
theme,
addFrame,
renderTo,
brokerName,
performOAuthRedirect({ url }) {
/*
if the broker login is implemented using OAuth redirects,
this callback will be called with the URL to redirect to.
After login, the client will redirect back to the configurated application URL.
After that redirect, the client application must use `confirmOAuth` to confirm
the session.
*/
},
onExit: ({ loggedIn }) => {
/* application can handle a successful broker login (e.g. show a SessionsTable or PortfolioTable) */
},
openExternalLink
}
<brokerize-broker-login-form ... />
Property | Description | optional |
---|---|---|
apiCtx | Instance of AuthorizedApiContext from @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |
returnToUrl | URL to return to after login | ✅ |
brokerName | The brokerName as per the GetBrokers endpoint from the API |
❌ |
addFrame | Add a "powered by brokerize" frame to the component | ✅ |
supportLink | Add a support link to the brokerize frame config, e.g. { emailSubject: 'Help needed for trading in XYZ app'}
|
✅ |
openExternalLink | A function for handling links to external documents, e.g. cost estimations | ✅ |
event | Description |
---|---|
guest | is fired when the user clicks the guest login |
login | is fired when the user has successfully logged in |
redirect | is fired when a redirect to the broker login page should take place |
As described in the OpenAPI specification, users can either log in with their brokerize account or create a guest user. This will create a guest user with the API and a corresponding AuthorizedApiContext
:
const user = await brokerizeClient.createGuestUser();
const apiCtx = brokerizeClient.createAuthorizedContext(user);
apiCtx
can now be used to interact with the API (you can also use that instance directly in your application code).
If you want to support users to choose between logging in with their brokerize credentials or using a guest account, use LoginForm
to retrieve either AuthorizedApiContext
like this:
Brokerize.Elements.createLoginForm({
renderTo: $el,
theme,
addFrame,
client: brokerizeClient,
onGuestLogin() {
client.createGuestUser().then(
(authCtxCfg) => {
setLogin(authCtxCfg);
},
(err) => showError(err)
);
},
onLogin(authCtxCfg) {
setLogin(authCtxCfg);
},
openExternalLink
});
function setLogin(authCtxCfg) {
apiCtx = client.createAuthorizedContext(cfg);
}
<brokerize-login ... />
Property | Description | optional |
---|---|---|
client | Instance of the @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |
event | Description |
---|---|
guest | is fired when the user clicks the guest login |
login | is fired when the user has successfully logged in |
The main component is the default goto component for the simplest and quickest brokerize experience, as all the default behavior is already interconnected and ready to use. You just need to integrate this one component and can use all of brokerize's features.
createBrokerizeMain({
authorizedApiContext,
theme,
renderTo,
addFrame,
useNavigation: true,
onNavigationStateChange(state) {
// react to interanal navigation changes
},
openExternalLink
});
<brokerize-main ... />
Property | Description | optional |
---|---|---|
apiCtx | Instance of AuthorizedApiContext from @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |
useNavigation | Show the default navigation bar on BrokerizeMain
|
✅ |
addFrame | Add a "powered by brokerize" frame to the component. Defaults to true. | ✅ |
supportLink | Add a support link to the brokerize frame config, e.g. { emailSubject: 'Help needed for trading in XYZ app'}
|
✅ |
openExternalLink | A function for handling links to external documents, e.g. cost estimations | ✅ |
returnToUrl | URL to return to after login | ✅ |
event | Description |
---|---|
navigationStateChange | is fired when the current navigational state is changed |
A view that allows the user to cancel an order (includes an order receipt and the form UI for selecting an authorization method, requesting a challenge etc.).
createCancelOrderForm({
authorizedApiContext,
theme,
addFrame,
renderTo,
sessionId,
onExit({ canceled }) {
/* when the process is completed or aborted (can be used to remove the view) */
},
openExternalLink
});
<brokerize-cancel-order-form ... />
Property | Description | optional |
---|---|---|
apiCtx | Instance of AuthorizedApiContext from @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |
orderId | Id of the order to show/edit | ❌ |
addFrame | Add a "powered by brokerize" frame to the component | ✅ |
supportLink | Add a support link to the brokerize frame config, e.g. { emailSubject: 'Help needed for trading in XYZ app'}
|
✅ |
event | Description |
---|---|
navigate | is fired when the user clicks a link in then orderReceipt |
exit | is fired when the changeOrderForm exits |
A view that allows the user to make changes to an order.
createChangeOrderForm({
authorizedApiContext,
theme,
addFrame,
renderTo,
orderId,
onExit() {
/* when the process is completed or aborted (can be used to remove the view) */
},
openExternalLink
});
<brokerize-change-order-form ... />
Property | Description | optional |
---|---|---|
apiCtx | Instance of AuthorizedApiContext from @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |
addFrame | Add a "powered by brokerize" frame to the component | ✅ |
supportLink | Add a support link to the brokerize frame config, e.g. { emailSubject: 'Help needed for trading in XYZ app'}
|
✅ |
orderId | Id of the order to show/edit | ❌ |
saveDownloadedFile | Custom implementation of "save download as..." | ✅ |
openExternalLink | A function for handling links to external documents, e.g. cost estimations | ✅ |
event | Description |
---|---|
exit | is fired when the changeOrderForm exits |
A form for trading a given ISIN in a given portfolio.
createOrderForm({
authorizedApiContext,
theme,
addFrame,
renderTo: document.getElementById('orderFormArea'),
isin: 'DE0007493991',
portfolioId: '<portfolioId>',
onOrderCreated(response) {
/* for example, show the order receipt after creation. */
},
openExternalLink
// quotesProvider
});
<brokerize-order-form ... />
Property | Description | optional |
---|---|---|
apiCtx | Instance of AuthorizedApiContext from @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |
addFrame | Add a "powered by brokerize" frame to the component | ✅ |
supportLink | Add a support link to the brokerize frame config, e.g. { emailSubject: 'Help needed for trading in XYZ app'}
|
✅ |
portfolioId | Id of the requested portfolio | ❌ |
isin | ISIN selected for trading | ❌ |
preferredExchangeId | One of the Exchange IDs as returned by the brokerize API's GetExchanges endpoint, will be set as the default exchange if supported by the broker | ✅ |
lockOrderDirection | If true, users cannot change the order direction. A direction must be provided in initialOrder.direction in this case. |
✅ |
overrideBrokerExchangeId | If provided, the given broker exchange id will be pre-selected in the OrderForm. Note that depending on PreparedTrade.noExchangeDefault , frontends are obligated to present a selection of exchanges before passing this value, as brokers may not allow pre-selecting exchanges. Make sure to only pass this value if the user has already selected an exchange and knows their options. The value will only be applied if it is available via PreparedTrade - the frontend should check this before passing the value. If you are not sure whether you should use it: don't and use preferredExchangeId instead |
✅ |
initialOrderCreateValues | The initial values to start the order form with | ✅ |
openExternalLink | A function for handling links to external documents, e.g. cost estimations | ✅ |
saveDownloadedFile | Custom implementation of "save download as..." | ✅ |
quotesProvider | Custom implementation of a quotes provider | ✅ |
event | Description |
---|---|
created | is fired when an order is created |
navigate | is fired when the user clicks the portfolio link |
Display a summary of order receipt data
createOrderReceipt({
authorizedApiContext,
theme,
addFrame,
renderTo: document.getElementById('area'),
orderId,
openExternalLink
});
<brokerize-order-receipt ... />
Property | Description | optional |
---|---|---|
apiCtx | Instance of AuthorizedApiContext from @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |
addFrame | Add a "powered by brokerize" frame to the component | ✅ |
supportLink | Add a support link to the brokerize frame config, e.g. { emailSubject: 'Help needed for trading in XYZ app'}
|
✅ |
orderId | Id of the order to show/edit | ❌ |
event | Description |
---|---|
navigate | is fired when the user clicks the portfolio link |
A view for listing the orders in the given portfolio.
createOrderTable({
authorizedApiContext,
theme,
addFrame,
renderTo,
portfolioId,
openExternalLink
});
<brokerize-order-table ... />
Property | Description | optional |
---|---|---|
apiCtx | Instance of AuthorizedApiContext from @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |
addFrame | Add a "powered by brokerize" frame to the component | ✅ |
supportLink | Add a support link to the brokerize frame config, e.g. { emailSubject: 'Help needed for trading in XYZ app'}
|
✅ |
portfolioId | Id of the requested portfolio | ❌ |
openExternalLink | A function for handling links to external documents, e.g. cost estimations | ✅ |
event | Description |
---|---|
cancelOrder | is fired when the user clicks cancel order menu item |
editOrder | is fired when the user clicks the change order menu item |
showReceipt | is fired when the user clicks the show receipt menu item |
Show a list of all portfolios that are added to the user's account.
createPortfolioTable({
authorizedApiContext,
theme,
addFrame,
renderTo,
onNavigate(portfolio: { id, portfolioName, ... }) {},
openExternalLink
});
<brokerize-portfolio-table ... />
Property | Description | optional |
---|---|---|
apiCtx | Instance of AuthorizedApiContext from @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |
addFrame | Add a "powered by brokerize" frame to the component | ✅ |
supportLink | Add a support link to the brokerize frame config, e.g. { emailSubject: 'Help needed for trading in XYZ app'}
|
✅ |
openExternalLink | A function for handling links to external documents, e.g. cost estimations | ✅ |
event | Description |
---|---|
navigate | is fired when the user clicks a link that should navigate to a different view |
Shows a combined view for one portfolio with important keyfigures like overall profit/loss in the footer bar, the list of open positions as well as open, cancelled and executed orders.
createPortfolioView({
addFrame,
portfolioId: string;
onBuy: (opts: { isin: string }) => {
/* handle the user's "buy" click here */
}
onSell: (opts: { isin: string; availableSize: number }) => {
/* handle the user's "sell" click here */
}
onCancelOrder: (opts: { orderId: string }) => {
/* handle the user's "cancel order" click here */
}
onChangeOrder: (opts: { orderId: string }) => {
/* handle the user's "change order" click here */
}
onShowReceipt: (opts: { orderId: string }) => {
/* handle the user's "show order receipt" click here */
},
openExternalLink
})
<brokerize-portfolio-view ... />
Property | Description | optional |
---|---|---|
apiCtx | Instance of AuthorizedApiContext from @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |
addFrame | Add a "powered by brokerize" frame to the component | ✅ |
supportLink | Add a support link to the brokerize frame config, e.g. { emailSubject: 'Help needed for trading in XYZ app'}
|
✅ |
portfolioId | Id of the requested portfolio | ❌ |
openExternalLink | A function for handling links to external documents, e.g. cost estimations | ✅ |
event | Description |
---|---|
buy | is fired when the user clicks the buy menu item |
sell | is fired when the user clicks the sell menu item |
showReceipt | is fired when the user clicks the showreceipt menu item |
editOrder | is fired when the user clicks the edit order menu item |
cancelOrder | is fired when the user clicks the cancel order menu item |
A view for listing the current open positions in the given portfolio.
createPositionsTable({
authorizedApiContext,
theme,
addFrame,
renderTo,
portfolioId,
onTradeInstrument: (opts: {
isin: string;
direction: Direction
}) => void,
openExternalLink
});
<brokerize-positions-table ... />
Property | Description | optional |
---|---|---|
apiCtx | Instance of AuthorizedApiContext from @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |
addFrame | Add a "powered by brokerize" frame to the component | ✅ |
supportLink | Add a support link to the brokerize frame config, e.g. { emailSubject: 'Help needed for trading in XYZ app'}
|
✅ |
portfolioId | Id of the requested portfolio | ❌ |
openExternalLink | A function for handling links to external documents, e.g. cost estimations | ✅ |
event | Description |
---|---|
buy | is fired when the user clicks the buy button |
sell | is fired when the user clicks the sell button |
A list of the user's active broker sessions. This is where users can log out from specific broker sessions and enable session TANs for sessions.
createSessionsTable({
authorizedApiContext,
theme,
addFrame,
renderTo,
onEnableSessionTan({ sessionId }) {
/* here: show the enable session tan form */
},
openExternalLink
});
<brokerize-sessions-table ... />
Property | Description | optional |
---|---|---|
apiCtx | Instance of AuthorizedApiContext from @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |
addFrame | Add a "powered by brokerize" frame to the component | ✅ |
supportLink | Add a support link to the brokerize frame config, e.g. { emailSubject: 'Help needed for trading in XYZ app'}
|
✅ |
parentHasNoPadding | For the brokerize frame: control whether the parent element already adds a padding | ✅ |
openExternalLink | A function for handling links to external documents, e.g. cost estimations | ✅ |
event | Description |
---|---|
enableSessionTan | is fired when the user clicks the enableSessionTan menu item |
A view for enabling session TAN for a session (the user may select an authorization method, request a challenge etc.).
createSessionTanForm({
authorizedApiContext,
addFrame,
theme,
renderTo,
sessionId,
onExit({ canceled }) {
/* when the process is completed or aborted (can be used to remove the view) */
},
openExternalLink
});
<brokerize-session-tan ... />
Property | Description | optional |
---|---|---|
apiCtx | Instance of AuthorizedApiContext from @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |
addFrame | Add a "powered by brokerize" frame to the component | ✅ |
supportLink | Add a support link to the brokerize frame config, e.g. { emailSubject: 'Help needed for trading in XYZ app'}
|
✅ |
sessionId | Id of the requested session | ❌ |
event | Description |
---|---|
exit | is fired when the sessionTanForm exits |
To use the default modals simply put a modalhost instance into your root layout.
// in your page, put sth like <div id="brokerize-modal"></div> at the end of your page (this makes sure our modal will be topmost)
const renderTo = document.getElementById('brokerize-modal');
const modalHost = createModalHost{
authorizedApiContext,
theme,
renderTo
});
/* whenever you recreate the modal host (e.g. when the authorizedApiContext must be replaced), make sure to destroy the existing one first,
as only one modal host is allowed globally at any given time. */
// modalHost.destroy();
To customize the behavior of certain modals you can get a reference to the modalService by importing it from the elements and overriding one or many of its methods.
import { modalService } from '@brokerize/elements';
modalService.override(...);
Where the interface of the modalService is defined as follows:
export declare interface ModalService {
showSecurityInformation(title: string, content: string): void;
showConfirm(msg: string): Promise<boolean>;
showSessionTanModal(sessionId: string): void;
setActivated(): void;
override(overrides: Partial<ModalService>): void;
showReceipt(data: ReceiptData, showActions: boolean, handleOrderTableAction: (e: any) => void): void;
showDetailedTable(table: Models.GenericTable): void;
showPositionDetail(
position: Models.Position,
row?: TableRow,
header?: Header,
handleTableAction?: (actionId: string, rowId: string) => void
): void;
}
<brokerize-modal-host ... />
Property | Description | optional |
---|---|---|
apiCtx | Instance of AuthorizedApiContext from @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |