brokerize elements
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.
how to install
The brokerize client libraries are not yet currently available, so you will need to get a token to be able to install it from our private package registry.
Once you have the token, this is how you add it to a project:
$ npm init -y
$ npm config set @brokerize:registry https://npm.pkg.github.com --location project
$ npm config set 'https://npm.pkg.github.com/:_authToken' --location project "<PROVIDED_GITHUB_PACKAGE_INSTALL_TOKEN>"
usage example
To use brokerize elements, an instance of brokerize client must be created first. This is used by the the UI elements 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 | ✅ |
theming
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'
};
How to use brokekerize-web-components
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 from our angular-example, using other frameworks might introduce tho need for a differnt syntax for propertybinding.
BrokerList
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
});
web component
<brokerize-broker-list ... />
properties
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
|
✅ |
events
event | Description |
---|---|
login | is fired when the user has accepted the terms and conditions and clicked on Login
|
BrokerLoginForm
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
}
Webcomponent
<brokerize-broker-login-form ... />
properties
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 | ✅ |
events
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 |
Brokerize Login
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);
}
web component
<brokerize-login ... />
properties
Property | Description | optional |
---|---|---|
client | Instance of the @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |
events
event | Description |
---|---|
guest | is fired when the user clicks the guest login |
login | is fired when the user has successfully logged in |
Brokerize Main
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
});
Webcomponent
<brokerize-main ... />
properties
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 | ✅ |
events
event | Description |
---|---|
navigationStateChange | is fired when the current navigational state is changed |
CancelOrderForm
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
});
Webcomponent
<brokerize-cancel-order-form ... />
properties
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'}
|
✅ |
events
event | Description |
---|---|
navigate | is fired when the user clicks a link in then orderReceipt |
exit | is fired when the changeOrderForm exits |
ChangeOrderForm
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
});
Webcomponent
<brokerize-change-order-form ... />
properties
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 | ✅ |
events
event | Description |
---|---|
exit | is fired when the changeOrderForm exits |
OrderForm
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
});
Webcomponent
<brokerize-order-form ... />
properties
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 | ✅ |
events
event | Description |
---|---|
created | is fired when an order is created |
navigate | is fired when the user clicks the portfolio link |
OrderReceipt
Display a summary of order receipt data
createOrderReceipt({
authorizedApiContext,
theme,
addFrame,
renderTo: document.getElementById('area'),
orderId,
openExternalLink
});
Webcomponent
<brokerize-order-receipt ... />
properties
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 | ❌ |
events
event | Description |
---|---|
navigate | is fired when the user clicks the portfolio link |
OrderTable
A view for listing the orders in the given portfolio.
createOrderTable({
authorizedApiContext,
theme,
addFrame,
renderTo,
portfolioId,
openExternalLink
});
Webcomponent
<brokerize-order-table ... />
properties
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 | ✅ |
events
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 |
PortfolioTable
Show a list of all portfolios that are added to the user's account.
createPortfolioTable({
authorizedApiContext,
theme,
addFrame,
renderTo,
onNavigate(portfolio: { id, portfolioName, ... }) {},
openExternalLink
});
Webcomponent
<brokerize-portfolio-table ... />
properties
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 | ✅ |
events
event | Description |
---|---|
navigate | is fired when the user clicks a link that should navigate to a different view |
PortfolioView
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
})
Webcomponent
<brokerize-portfolio-view ... />
properties
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 | ✅ |
events
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 |
PositionsTable
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
});
Webcomponent
<brokerize-positions-table ... />
properties
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 | ✅ |
events
event | Description |
---|---|
buy | is fired when the user clicks the buy button |
sell | is fired when the user clicks the sell button |
SessionsTable
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
});
Webcomponent
<brokerize-sessions-table ... />
properties
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 | ✅ |
events
event | Description |
---|---|
enableSessionTan | is fired when the user clicks the enableSessionTan menu item |
SessionTanForm
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
});
Webcomponent
<brokerize-session-tan ... />
properties
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 | ❌ |
events
event | Description |
---|---|
exit | is fired when the sessionTanForm exits |
ModalHost
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;
}
Webcomponent
<brokerize-modal-host ... />
properties
Property | Description | optional |
---|---|---|
apiCtx | Instance of AuthorizedApiContext from @brokerize/client
|
❌ |
theme | You can use the brokerize theme designer to build a theme JSON | ✅ |