brokerize elements

@brokerize/elements is the official UI 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 install them like any other npm package:

$ 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>',
	// provide global dependencies
	fetch: globalThis.fetch.bind(globalThis), // optionally, a custom fetch implementation can be used
	createAbortController: () => new AbortController(), // optionally, a custom AbortController can be used
	createWebSocket: (url, protocol) => new WebSocket(url, protocol) // optionally, a custom WebSocket implementation can be used
});

Applications create temporary brokerize guest users for accessing the API. This code creates 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 in the scope if the newly created user (you can also use that instance directly in your application code). The user object can be stored as JSON in order to authenticate as the same user again. Note that the created credentials' lifetime depends on the client configuration. By default, those temporary users are deleted at night.

Now that you have a brokerize client instance as well as an AuthorizedApiContext, you can show the list of available brokers (or any other view) like this:

createBrokerList({
	authorizedApiContext,
	theme,
	addFrame,
	renderTo,
	onLogin({ brokerName }) {
		// show the login process for broker `brokerName` here
	},
	openExternalLink
});

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.

Overview

A view for viewing the list of active brokerage sessions and portfolios and for managing session state (for example: enable/disable Session TAN). It also presents the list of available brokers for adding logins, so that it can be used as a starting point for logging in to brokers as well as a view for selecting the portfolio for trading.

Brokerize.Elements.createOverview({
	theme,
	renderTo: resetRenderTo(),
	authorizedApiContext: globalApiCtx,
	onNavigate(portfolio) {
		/* navigate to the selected portfolio view, e.g. by calling `createPortfolioView(...)` */
		// showPortfolioView(portfolio.id);
	},
	onLogin({ brokerName }) {
		/* open the broker login for the given brokerName. */
		// Brokerize.Elements.createBrokerLoginForm(...)
	}
});

web component

<brokerize-overview ... />

| Property | Description | optional | | :------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | | authorizedApiContext | 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'} | ✅ | | 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 | | navigage | is fired when the user navigates to a portfolio |

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

NOTE: createBrokerLoginForm does not actually present a login form directly in most cases but rather triggers an OAuth redirect. This depends on the client configuration and specific demands of brokers and/or partners. By default, all brokers use an OAuth-style login flow.

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

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