# Mobile widgets (/vela-pro/customization/mobile/widgets)



Standalone module widgets do not have a separate mobile mode option. Each widget fills the container you mount it in and adapts to that container's dimensions. Building a phone interface with Vela Pro widgets comes down to giving each widget a sized container and keeping live feeds active only for the visible pane.

The example below builds a three-tab mobile screen (**Chart**, **Watchlist**, and **Trade**) where tapping a symbol in the watchlist opens it on the chart. For full widget props, callbacks, and controller sharing, see [Standalone widgets](/vela-pro/modules/widgets).

## Tabbed mobile layout [#tabbed-mobile-layout]

Initialize Vela Pro and create the workspace first. Pass `orderPanel: false` and `phoneSheet: false` to `trading()` in `plugins` because the custom **Trade** tab replaces the built-in trading panel and mobile sheet. Pin `layoutMode: 'mobile'` so the workspace keeps its mobile chrome even when its tab panel is hidden with `display: none` (which reports zero width):

```ts
import { VelaWorkspace } from '@luxalgo/vela/workspace';
import { BinanceProvider } from '@luxalgo/vela/providers/binance';
import { enableVelaPro } from '@luxalgo/vela-pro';
import { trading } from '@luxalgo/vela-pro-trading';

enableVelaPro({ plugins: [trading({ orderPanel: false, phoneSheet: false })] });

const workspace = new VelaWorkspace('#chart', {
    layout: false,
    layoutMode: 'mobile', // Pinned because hidden tab panels report zero width
    symbol: 'BTCUSDT',
    timeframe: '60',
    live: true,
    providers: { binance: () => new BinanceProvider() },
    persist: true,
});
```

Next, mount `createWatchlist` and `createOrderTicket` in sibling panes and switch visibility when the active tab changes:

```ts
import { DARK_THEME } from '@luxalgo/vela';
import { ensureUIHost } from '@luxalgo/vela/ui';
import type { VelaWorkspace } from '@luxalgo/vela/workspace';
import { ProviderQuotes } from '@luxalgo/vela-pro/plugin';
import { createWatchlist, watchlistController } from '@luxalgo/vela-pro-watchlist';
import { createOrderTicket, tradingController } from '@luxalgo/vela-pro-trading';

declare const workspace: VelaWorkspace; // Workspace instance created above

const ctx = workspace.context();
const data = () => ctx.chart.data;
const el = (id: string): HTMLElement => document.getElementById(id)!;
const panes = { chart: el('chart'), watchlist: el('watchlist'), trade: el('trade') };
const app = el('app');
ensureUIHost(app, DARK_THEME); // Applies theme tokens to menus and dialogs mounted in `host`

const watchlist = createWatchlist({
    controller: watchlistController()!,
    quotes: new ProviderQuotes(data),
    directory: data,
    host: app,
    active: false,
    onSelectSymbol: (symbol) => {
        ctx.setSymbol(symbol);
        show('chart');
    },
});
const ticket = createOrderTicket({ controller: tradingController()!, host: app });
panes.watchlist.append(watchlist.el);
panes.trade.append(ticket.el);

function show(tab: string): void {
    for (const [name, pane] of Object.entries(panes)) pane.hidden = name !== tab;
    // Keep live feeds active only for the visible widget and sync the current symbol.
    watchlist.update({ symbol: ctx.symbol, active: tab === 'watchlist' });
    ticket.update({ symbol: ctx.symbol, active: tab === 'trade' });
}

for (const button of document.querySelectorAll<HTMLElement>('[data-tab]')) {
    button.addEventListener('click', () => show(button.dataset.tab!));
}
show('chart');
```

Stack the three panes inside a full-height flex container above the tab bar:

```html
<div id="app">
    <div id="panes">
        <div id="chart"></div>
        <div id="watchlist" hidden></div>
        <div id="trade" hidden></div>
    </div>
    <div class="tabs">
        <button data-tab="chart">Chart</button>
        <button data-tab="watchlist">Watchlist</button>
        <button data-tab="trade">Trade</button>
    </div>
</div>
```

```css
#app { display: flex; flex-direction: column; height: 100dvh; }
#panes { position: relative; flex: 1; min-height: 0; }
#panes > div { position: absolute; inset: 0; }
#trade { overflow-y: auto; background: var(--vela-bg); }
.tabs { display: flex; padding-bottom: env(safe-area-inset-bottom); }
.tabs button { flex: 1; height: 48px; }
```

Passing `watchlistController()` and `tradingController()` connects both standalone widgets to the workspace's shared controllers. Watchlists stay synchronized with the workspace, and orders submitted from the **Trade** tab appear directly on the chart.

## Sizing and feed lifecycle [#sizing-and-feed-lifecycle]

* **Container dimensions**: Every widget stretches to fill its parent element and measures its layout from that container. In the stylesheet above, `#panes > div` positions each pane across the full area above the tab bar. Mounting a widget inside a zero-height container renders nothing visible.
* **Active feed management**: Pass `update({ active: false })` whenever hiding a widget instead of toggling CSS visibility alone. When inactive, `createWatchlist` closes its live quote subscriptions while preserving the last received values on each row, then reopens the feeds and remeasures when `active: true` is restored. Setting `active: false` also clears any draft order on `createOrderTicket` and closes market depth and trade streams on `createOrderBook`.
* **Symbol synchronization**: Passing `ctx.symbol` inside `show()` keeps hidden tabs aligned because the chart's active symbol cannot change while the **Chart** tab is hidden. In layouts where a widget stays visible next to the chart, subscribe to live symbol changes with `onActiveSymbol(ctx, (symbol) => widget.update({ symbol }))` from `@luxalgo/vela-pro/plugin`.
* **Overlay host and theming**: Widget menus and dialogs portal into the `host` element. Pass a persistent outer container such as `#app` and call `ensureUIHost(host, theme)` (from `@luxalgo/vela/ui` in Vela's open-source core) once so portaled overlays inherit theme tokens and dismiss cleanly on tab switches.
* **Order ticket scrolling and background**: `createOrderTicket` renders without an opaque background or internal scroll container. Set `overflow-y: auto` and `background: var(--vela-bg)` on its wrapper element (`#trade`), using the `--vela-bg` variable defined by `ensureUIHost`.

<Warning>
  Stylesheets from the core and Vela Pro declare their rules inside CSS cascade layers (`@layer vela.*`). Any unlayered CSS rule in your page overrides layered library styles regardless of selector specificity, including bare element selectors. For example, an unlayered `nav { display: flex }` rule matches the workspace's internal `<nav>` sidebar and forces it visible in the mobile layout. Scope your application styles with classes or IDs, or place base resets inside a lower-priority `@layer`.
</Warning>

## Widget behavior in narrow containers [#widget-behavior-in-narrow-containers]

Most widgets adapt to their own container width rather than the browser viewport. `createAlertsList`, `createJournalPanel`, and `createCalendar` use a single fluid layout at all widths.

| Widget                                          | Responsive behavior                                                                                                                                                                      |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Watchlist (`createWatchlist`)                   | Measures its container width. Hides the sparkline column below 380px and the volume column below 450px. At 300px and narrower, switches to compact row padding and smaller symbol icons. |
| Watchlist advanced view (`createWatchlistView`) | Measures its container width and stacks its side-by-side panels into a single column as the container narrows.                                                                           |
| Order ticket (`createOrderTicket`)              | Renders a single-column form at all widths and sets decimal keypad hints on price and size inputs.                                                                                       |
| Trading panel (`createTradingPanel`)            | Shows a left-hand account summary column at 720px and wider. Below 720px, moves account metrics into a horizontal strip under the header.                                                |
| Order book (`createOrderBook`)                  | Scales the number of visible price rows per side in Book view to fit the container height, clamped between 3 rows and the configured `rows` limit.                                       |
| Journal full view (`createJournalView`)         | Follows viewport width rather than container width. At viewports 1100px and narrower, collapses multi-column grids to one or two columns and hides the table of contents.                |

## Tablet layouts [#tablet-layouts]

On tablets and larger touch screens, you can place the workspace and standalone widgets side by side in a CSS Grid or Flexbox layout with `active: true` on every visible widget. Each widget measures its own container independently, and the workspace chooses its layout mode from the chart column's width. On a touch screen (`(pointer: coarse)`), a chart column narrower than 920px uses the mobile layout, while a column 920px or wider uses the desktop layout. See [Responsive layout](/vela-pro/customization/mobile/responsive#breakpoints-and-layoutmode) for the full breakpoint table.

When the chart container stays visible in a multi-column layout, keep `layoutMode` set to `'auto'`. You can retain the trading module's built-in order panel or disable it with `orderPanel: false` in favor of a standalone `createOrderTicket` pane.

## Related [#related]

* [Standalone widgets](/vela-pro/modules/widgets)
* [Responsive layout](/vela-pro/customization/mobile/responsive)
* [iOS and Android WebViews](/vela-pro/customization/mobile/native-apps)
* [Theming and branding](/vela-pro/customization/theme)
