README.md

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 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

usage example

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

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 brokerize-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 valid for Angular (and it's way of binding properties). Most frameworks allow to integrate custom elements similarly.

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
returnToUrl URL to return to after login

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