newWatchListWidget

newWatchListWidget is a constructor function for creating the Watch List widget.

Widget Constructor

Call newWatchListWidget to create a widget instance inside a browser DOM element.

import { newWatchListWidget } from '@dxfeed-widgets/watch-list'

const domNode = document.getElementById('widget-container')
const dataProviders = {
    ipfPath: '/your-path/ipf',
    ipfAuthHeader: 'your-header',
    feedPath: 'wss://your-path/feed',
    feedAuthHeader: 'your-header',
    fundamentalsPath: '/api/fundamentals',
    fundamentalsAuthHeader: 'your-header',
    schedulePath: '/api/schedule'
}
const widget = newWatchListWidget({
  element: domNode,
  providers: dataProviders,
})

Signature

newWatchListWidget(props: WidgetConstructorProps): WidgetAPI

Returns

An WidgetAPI object.

WidgetConstructorProps

Name	Type	Description
element	HTMLElement	A DOM element where the widget should be attached.
providers	Providers	An object with configuration for data providers. Refer to the Data Providers section for details
config optional	Config	Initial configuration of the widget
state optional	State	Initial state of the widget
theme optional	ThemeName | Theme	Initial theme of the widget. Refer to the Styling section for details

Widget API

getConfig

Gets the current widget config.

Signature

getConfig(): Config

Returns

Config

---

setConfig

Sets widget config.

Signature

setConfig(config: Config): void

Parameters

Name	Type	Description
config	Config	Configuration object. Omitted or undefined properties will be set to default

---

getState

Gets the current widget state.

Signature

getState(): State

Returns

State

---

updateState

Updates widget state.

Signature

updateState(state: Partial<State>): void

Parameters

Name	Type	Description
state	Partial<State>	State object. Merges with the previous state object.

---

addStateListener

Sets up a function that will be called whenever the state or specified field is changed.

Signature

addStateListener(stateChangeCallback: (state: State) => void): void
addStateListener(field: keyof State, fieldChangeCallback: (field: State[keyof State]) => void): void

Parameters

Name	Type	Description
stateChangeCallback	(state: State) => void	Function that will be called whenever the state is changed.

Or

Name	Type	Description
field	keyof State	The state field to listen for.
fieldChangeCallback	(value: State[keyof State]) => void	Function that will be called whenever the specified field is changed.

---

removeStateListener

Removes an state listener previously registered with addStateListener

Signature

removeStateListener(stateChangeCallback: (state: State) => void): void
removeStateListener(field: keyof State, fieldChangeCallback: (field: State[keyof State]) => void): void

Parameters

Name	Type	Description
stateChangeCallback	(state: State) => void	Listener that will be removed.

Or

Name	Type	Description
field	keyof State	The state field for which to remove a listener.
fieldChangeCallback	(value: State[keyof State]) => void	Listener that will be removed.

---

setSlot

Inserts custom markup into widget UI. Refer to the Extend widget UI section for details.

Signature

setSlot(slot: Slot, element: HTMLElement): void

Parameters

Name	Type	Description
slot	Slot	The place where a provided element is inserted.
element	HTMLElement	An element that is inserted.

---

setTheme

Sets widget theme.

Signature

setTheme(theme: Theme | ThemeName): void

---

unmount

Destroys the widget.

Signature

unmount(): void

Data Providers

The Data Providers object supplies an information about the endpoints required by the widget, such as the path to the endpoint and the authorization key.

interface WatchListWidgetDataProviders {
  ipfPath: string
  ipfAuthHeader: string
  feedPath: string
  feedAuthHeader: string
  fundamentalsPath: string
  fundamentalsAuthHeader: string
  schedulePath: string
}

Properties

Name	Type	Description
ipfPath	string	A string containing the path to the endpoint.
ipfAuthHeader	string	A string containing the authentication header for the endpoint.
feedPath	string	A string containing the path to the endpoint.
feedAuthHeader	string	A string containing the authentication header for the endpoint.
fundamentalsPath	string	A string containing the path to the endpoint.
fundamentalsAuthHeader	string	A string containing the authentication header for the endpoint.
schedulePath	string	A string containing the path to the endpoint.

Configuration

Configuration is an object that defines the basic behavior of a widget and allows enabling or disabling widget features that cannot be configured within the widget's user interface.

Type

interface WatchListWidgetConfig {
  symbolSearchTypes?: WatchListWidgetSymbolSearchType[],
  availableColumns?: WatchListColumnId[],
  symbolSearchViewMode?: SymbolSearchViewMode,
  dataExportEnabled?: boolean,
  rowRemovalEnabled?: boolean,
  sortable?: boolean,
  filterable?: boolean,
  reorderable?: boolean,
  reorderableRows?: boolean,
  resizable?: boolean,
  columnSelectMenuEnabled?: boolean,
  delayNotificationEnabled?: boolean,
  symbolScheduleStatusEnabled?: boolean,
  timezone?: string,
  locale?: LocaleSettings,
}

Properties

Name	Type	Default	Description
symbolSearchTypes Optional	WatchListWidgetSymbolSearchType[]	[ 'STOCK', 'FUTURE', 'OPTION', 'FOREX', 'ETF', 'PRODUCT', 'INDEX', 'SPREAD' ]	A list of instrument types uses for symbols search.
availableColumns Optional	WatchListColumnId[]	Default columns "range52Week", "sparklineChart", "symbol", "tradingStatus", "opol", "symbolDescription", "currency", "instrType", "bidPrice", "bidSize", "bidTime", "askPrice", "askSize", "askTime", "spread", "spreadPercent", "midPrice", "lastPrice", "markPrice", "markChange", "markChangePercent", "dayVwap", "dayVolume", "lastUpdateTime", "dayBidVolume", "dayAskVolume", "prevDayClosePrice", "changePrevDayClosePrice", "changePrevDayClosePricePercent", "dayOpenPrice", "changeCurDayOpenPrice", "changeCurDayOpenPricePercent", "gapDay", "gapDayPercent", "dayHighPrice", "dayLowPrice", "rangeDay", "positionInRangeDayPercentage", "sessionEndTime", "tradingStatusReason", "haltStartTime", "assetClass", "expDate", "strike", "openInterest", "optTheoPriceTime", "optTheoPrice", "optUnderlyingPrice", "optExpDivRate", "optExpIntRate", "optGreeksTime", "optImpVol", "optDelta", "optGamma", "optTheta", "optRho", "optVega", "settlementPrice", "priceType", "standardName", "marketCap", "enterpriseValue", "sharesOutstanding", "sharesFloat", "epsDilutedTtm", "trailingPe", "forwardPe", "trailingDividendYield", "forwardDividendYield", "payoutRatio", "operatingMargin", "profitMargin", "roeTtm", "roaTtm", "beta5Y", "earningDate", "forwardDividendYear", "exDividendDate", "quarterlyRevenueGrowth", "heldByInsider", "heldByInstitutions", "pegRatio", "lastSplitFactor", "lastSplitDate", "employees", "country", "website", "sector", "industry", "ebitda", "epsTrailingTtm", "psRatio", "yearOfEstablishment", "companyDescription", "grossMargin", "cash", "currentAssets", "currentDebt	Available list of columns to select in the columns menu
symbolSearchViewMode Optional	SymbolSearchViewMode	'available'	View mode of the symbol search in the toolbar.
dataExportEnabled Optional	boolean	false	A flag that controls a visibility of an export button.
rowRemovalEnabled Optional	boolean	true	A flag that controls a ability to remove rows.
sortable Optional	boolean	true	A flag that controls the table sorting feature.
filterable Optional	boolean	true	A flag that controls the filtering function of table columns.
reorderable Optional	boolean	true	A flag that controls the column reorder feature.
reorderableRows Optional	boolean	true	A flag that controls the rows reorder feature.
resizable Optional	boolean	true	A flag that controls the column resizing feature.
columnSelectMenuEnabled Optional	boolean	false	A flag that controls the column select menu feature visibility. Disabling this feature will lead to inability to change columns.
delayNotificationEnabled Optional	boolean	false	A flag that controls a visibility of an data delay notification.
symbolScheduleStatusEnabled Optional	boolean	false	A flag that controls a visibility of symbol schedule status in symbol column in table
timezone Optional	string	client environment timezone	String corresponds to IANA Time Zone name used to display dates in spicified time zone
locale Optional	LocaleSettings	{ language: 'en', dateLocale: 'en-GB' }	An object that defines the language and regional settings of the widget.

State

State is an object that represents the state of the widget.

Type

interface WatchListWidgetState {
  symbols: string[],
  selectedSymbol?: string,
  columns: WatchListColumnId[],
  columnSizes: WatchListColumnSizes,
  filters: WatchListFilters,
  sort?: Sort<WatchListColumnId>,
}

Properties

Name	Type	Default	Description
symbols	string[]	[]	A list of strings containing symbols that are added to the table. The symbols are displayed in the order specified by the array.
selectedSymbol Optional	string	undefined	A string containing the symbol selected in the table.
columns	WatchListColumnId[]	[ 'symbol', 'lastPrice' ]	A list of column identifiers that are added to the table. The columns are displayed in the order specified by the array.
columnSizes	WatchListColumnSizes	{}	An object that specifies column sizes where key is a column identificator and value is a column width in pixels. If the object does not contain a column width, then default width is used.
filters	WatchListFilters	{}	An object that defines enabled filters and their parameters.
sort Optional	Sort<WatchListColumnId>	undefined	An object that defines table sort.

Type Reference

Slot

Type

'header'

---

WatchListColumnId

Available column ids by default column dictionary

- range52Week
- sparklineChart
- symbol
- tradingStatus
- opol
- symbolDescription
- currency
- instrType
- bidPrice
- bidSize
- bidTime
- askPrice
- askSize
- askTime
- spread
- spreadPercent
- midPrice
- lastPrice
- markPrice
- markChange
- markChangePercent
- dayVwap
- dayVolume
- lastUpdateTime
- dayBidVolume
- dayAskVolume
- prevDayClosePrice
- changePrevDayClosePrice
- changePrevDayClosePricePercent
- dayOpenPrice
- changeCurDayOpenPrice
- changeCurDayOpenPricePercent
- gapDay
- gapDayPercent
- dayHighPrice
- dayLowPrice
- rangeDay
- positionInRangeDayPercentage
- sessionEndTime
- tradingStatusReason
- haltStartTime
- assetClass
- expDate
- strike
- openInterest
- optTheoPriceTime
- optTheoPrice
- optUnderlyingPrice
- optExpDivRate
- optExpIntRate
- optGreeksTime
- optImpVol
- optDelta
- optGamma
- optTheta
- optRho
- optVega
- settlementPrice
- priceType
- standardName
- marketCap
- enterpriseValue
- sharesOutstanding
- sharesFloat
- epsDilutedTtm
- trailingPe
- forwardPe
- trailingDividendYield
- forwardDividendYield
- payoutRatio
- operatingMargin
- profitMargin
- roeTtm
- roaTtm
- beta5Y
- earningDate
- forwardDividendYear
- exDividendDate
- quarterlyRevenueGrowth
- heldByInsider
- heldByInstitutions
- pegRatio
- lastSplitFactor
- lastSplitDate
- employees
- country
- website
- sector
- industry
- ebitda
- epsTrailingTtm
- psRatio
- yearOfEstablishment
- companyDescription
- grossMargin
- cash
- currentAssets
- currentDebt

Type

string

---

WatchListFilters

Type

Partial<Record<WatchListColumnId, Filter>>

---

WatchListWidgetSymbolSearchType

Type

'STOCK' | 'FUTURE' | 'OPTION' | 'FOREX' | 'ETF' | 'PRODUCT' | 'INDEX' | 'SPREAD'

---

WatchListColumnSizes

Type

Partial<Record<WatchListColumnId, number>>

---

SnapshotSize

Type

number | 'Full'

---

SymbolSearchViewMode

Type

'available' | 'hidden' | 'value-only'

---

ToolbarSelectorViewMode

Type

'available' | 'hidden'

---

Sort

An object that defines table sort.

Type

{
  property: WatchListColumnId,
  direction: SortDirection,
}

---

SortDirection

Direction of the sort.

Type

'ascending' | 'descending'

---

Filter

Type

{
  name: string,
  argument: A,
}

---

LocaleSettings

An object that defines the language and regional settings of the widget.

Type

{
  language: Language,
  dateLocale: string,
}

---

Language

Type

'en' | 'de' | 'ar'