# Responsive layout (/vela-pro/customization/mobile/responsive)



`VelaWorkspace` uses a single responsive build across desktop and mobile screens. In a narrow container, the workspace replaces the desktop top toolbar and bottom bar with one compact bottom bar, presents menus as bottom sheets and dialogs full-screen, and adapts Vela Pro features to touch navigation.

Layout switching is automatic by default. Set `layoutMode` only when you want to pin `'mobile'` or `'desktop'` regardless of container width:

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

enableVelaPro();

const workspace = new VelaWorkspace('#chart', {
    layout: false,
    layoutMode: 'mobile', // 'auto' (default) | 'mobile' | 'desktop'
    symbol: 'BTCUSDT',
    timeframe: '60',
    live: true,
    providers: { binance: () => new BinanceProvider() },
    persist: true,
});
```

## Breakpoints and layoutMode [#breakpoints-and-layoutmode]

With `layoutMode: 'auto'`, the workspace measures its own container width rather than the browser viewport or device user agent:

| Container width | Pointer                                    | Layout  |
| --------------- | ------------------------------------------ | ------- |
| Under 640px     | Any                                        | Mobile  |
| 640px to 919px  | Coarse (`(pointer: coarse)`, touch screen) | Mobile  |
| 640px to 919px  | Fine (mouse or trackpad)                   | Desktop |
| 920px and wider | Any                                        | Desktop |

Pointer detection evaluates the `(pointer: coarse)` CSS media query. A chart placed inside a 380px sidebar column on a desktop browser renders the mobile layout, while a 1000px chart on a tablet renders the desktop layout.

Breakpoint transitions happen live. When the container resizes across a threshold or the user rotates a device, the workspace updates its chrome in place and closes any open menu, sheet, or dialog. Pass `layoutMode: 'mobile'` or `layoutMode: 'desktop'` to lock the layout at all widths, such as on dedicated phone screens or inside [iOS and Android WebViews](/vela-pro/customization/mobile/native-apps).

<Note>
  In `'auto'` mode, a container with zero width resolves to `'desktop'`. If you hide the chart container with `display: none` (for example, inside an inactive tab panel), the workspace switches to the desktop layout while hidden and switches back when shown. Pin `layoutMode` when hiding the workspace container with `display: none`.
</Note>

The workspace root element (`workspace.root`) sets `data-layout="mobile"` or `data-layout="desktop"`, which you can target in custom CSS rules.

## Mobile chrome [#mobile-chrome]

When the workspace enters the mobile layout, the shell adjusts its controls for touch interaction:

* **Single bottom bar**: Replaces the desktop top toolbar and bottom bar. From left to right, it contains the symbol button, timeframe button, indicators button, drawings button, an overflow menu (three dots), and chart settings. Multi-chart workspaces add a maximize button to view the active cell by itself.
* **Bottom sheets**: Dropdown menus become bottom sheets. The timeframe sheet displays date presets and the timeframe grid. The drawings sheet provides a search input, tabbed tool categories, and favorite toggles. The overflow sheet groups undo, redo, screenshot, chart type selection (including Footprint and TPO), side panels, the alerts list, custom actions, and (in multi-chart workspaces) layout presets and sync toggles.
* **Full-screen dialogs**: Symbol search, the indicator menu, indicator settings, and chart settings open full-screen.
* **Floating drawing pill**: The side drawing toolbar is hidden. Selecting a tool in the drawings sheet displays a floating pill over the chart with magnet mode, stay-in-drawing-mode, eraser, and deselect buttons.
* **Overlay side panels**: Side panels open over the chart instead of docking in an adjacent column.
* **Collapsed indicator legend**: The indicator legend starts collapsed behind a count badge. In a multi-chart workspace, tapping the badge opens the object tree.
* **No hover-only controls**: Hover-triggered controls, including the floating zoom/reset cluster and per-pane header buttons, are hidden.

All bottom sheets and full-screen dialogs operate on the active chart cell.

## Touch gestures [#touch-gestures]

| Gesture                          | Behavior                                                                                                                |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| One-finger drag on plot          | Pans the chart with inertial scrolling on release.                                                                      |
| Two-finger pinch                 | Zooms the time axis, anchored at the midpoint between fingers.                                                          |
| Long-press on plot               | Shows the crosshair and data readout. Moving your finger scrubs bars without panning, and lifting clears the crosshair. |
| Double-tap on plot               | Maximizes the tapped price or indicator pane. Double-tapping again restores the pane split.                             |
| Drag on price or time axis       | Rescales that axis.                                                                                                     |
| Double-tap on price axis         | Resets that pane's price scale to auto.                                                                                 |
| Double-tap on time axis          | Fits the visible range to the loaded bars.                                                                              |
| Long-press on price or time axis | Opens the price scale sheet or timezone sheet instead of the desktop context menu.                                      |

Because the chart processes touch input through pointer events, these gestures also work on touch screens displaying the desktop layout. The price scale and timezone bottom sheets are the only exception and open exclusively in the mobile layout.

## Vela Pro features on mobile [#vela-pro-features-on-mobile]

| Feature                                                                 | Mobile behavior                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Symbol search](/vela-pro/data/symbols/symbol-search)                   | Opens full-screen from the bottom bar's symbol button without the symbol inspector or keyboard shortcut footer.                                                                                                                                                                                                                                                                                                                     |
| [Indicator menu](/vela-pro/indicators/library)                          | Opens full-screen from the bottom bar's indicators button with category tabs in a single horizontally scrollable row and no detail pane. The desktop favorites dropdown caret is omitted.                                                                                                                                                                                                                                           |
| [Indicator templates](/vela-pro/persistence/stores/indicator-templates) | Appears as a row in the overflow menu ahead of the side panels.                                                                                                                                                                                                                                                                                                                                                                     |
| [Bar replay](/vela-pro/charts/replay)                                   | Appears as a row in the overflow menu ahead of the side panels. Activating replay displays a vertical cut line centered on the chart with a bottom prompt offering **Cancel** and **Start here**. Dragging and releasing the line or tapping a bar starts replay there. The replay transport bar docks above the bottom bar as a single scrolling row without a pin toggle, and its date readout does not open the calendar picker. |
| [Strategy tester](/vela-pro/indicators/backtesting/strategy-tester)     | Omits the summary strip and does not cover the chart automatically on initial calculation. Once results are available, a floating **Backtest** button appears above the bottom bar to open the full report over the chart.                                                                                                                                                                                                          |
| [Trading](/vela-pro/modules/trading/overview)                           | When installed, adds a **Trade** button after the timeframe button that opens a bottom sheet with **Order** (order ticket) and **Positions** (trading panel) tabs.                                                                                                                                                                                                                                                                  |
| Side rail                                                               | Hidden. Side panels and rail entries appear as rows in the overflow menu.                                                                                                                                                                                                                                                                                                                                                           |
| Bottom dock                                                             | Dockable panels with rail entries (such as the trading panel) open from the overflow menu. When maximized, the dock stops above the bottom bar.                                                                                                                                                                                                                                                                                     |

Neither symbol search nor the indicator menu auto-focuses its search input when opened, keeping the virtual keyboard from covering the list until the user taps the input.

### Trading sheet [#trading-sheet]

The trading sheet opens at roughly two-thirds of the workspace height so the chart stays visible above it. Dragging the top handle upward expands the sheet to nearly full height, and dragging downward dismisses it. Focusing an input field expands the sheet automatically, and starting an order on the chart opens the sheet to the **Order** tab.

Pass `phoneSheet: false` to `trading()` in the `plugins` array to disable the **Trade** button and bottom sheet. When disabled, the order panel remains accessible from the overflow menu and the on-chart Buy/Sell buttons stay active:

```ts
import { enableVelaPro } from '@luxalgo/vela-pro';
import { trading } from '@luxalgo/vela-pro-trading';

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

## Custom action placement [#custom-action-placement]

Custom topbar actions registered through `registerWidgetAction` (from `@luxalgo/vela/plugin` in Vela's open-source core) use the `mobile` field to control mobile placement. Set `mobile: 'bar'` to place an icon button directly in the bottom bar, or `mobile: 'menu'` to place a labeled row in the overflow menu:

```ts
import { registerWidgetAction } from '@luxalgo/vela/plugin';

declare function openEvents(symbol: string): void;

registerWidgetAction({
    id: 'acme.events',
    target: 'topbar',
    label: 'Events',
    icon: 'calendar',
    mobile: 'bar',
    // Optional filter to show this action only in the mobile layout.
    when: (ctx) => ctx.host.closest('[data-layout]')?.getAttribute('data-layout') === 'mobile',
    run: (ctx) => openEvents(ctx.symbol),
});
```

When `mobile` is omitted, actions with `align: 'left'` render as bottom bar buttons and all other actions render in the overflow menu. Within the overflow menu, left-aligned actions (`align: 'left'` with `mobile: 'menu'`) appear ahead of the side panel entries, while right-aligned actions appear at the end. Vela Pro uses `mobile: 'menu'` on Bar replay and Indicator templates to keep the bottom bar compact.

Call `registerWidgetAction` before constructing `VelaWorkspace`. The workspace re-evaluates `when` each time the layout switches between `'desktop'` and `'mobile'`. For the full descriptor reference, see [Widget actions](/vela/contributing/plugin-sdk#widget-actions--registerwidgetaction) in the core documentation.

## Related [#related]

* [Mobile widgets](/vela-pro/customization/mobile/widgets)
* [iOS and Android WebViews](/vela-pro/customization/mobile/native-apps)
* [Interface layout](/vela-pro/customization/interface)
* [Mobile workspace layout in the core](/vela/user/workspace#mobile)
