# Trading primitives

## Overview

**Trading primitives** is a low-level mechanism that allows you to draw order, position, and execution lines directly on the chart.

This approach is fundamentally different from the standard [Broker API] integration.
While the Broker API requires implementing a backend trading server to display real trading data, trading primitives act as specialized drawing tools.
This allows creating visual elements without needing a full trading logic implementation.

:::caution

Starting from version 29, the methods for creating trading primitives are only available in [Trading Platform].

:::

## Create trading primitive

You can create primitives using the following methods of the chart's API object ([`IChartWidgetApi`]).

- [`createOrderLine`]
- [`createPositionLine`]
- [`createExecutionShape`]

After the primitive is created, you can customize and interact with it using the API adapter.
For example, the code sample below adds a new order line on the chart using the `createOrderLine` method.

```javascript
const orderLine = await widget.activeChart().createOrderLine()

orderLine
    .setTooltip("Additional order information")
    .setModifyTooltip("Modify order")
    .setCancelTooltip("Cancel order")
    .setText("STOP: 73.5 (5,64%)")
    .setQuantity("2");
```

You can also attach callback functions to handle actions like modifying, canceling/closing, or moving/reversing lines.
Inside a callback function, the `this` keyword refers to the API adapter of the primitive itself (e.g., `IOrderLineAdapter`).
This allows you to call methods directly on the object in response to an event.

```javascript
const orderLine = await widget.activeChart().createOrderLine();

orderLine
    .setQuantity("5")
    .setPrice(160)
    // Enables the "Cancel" button
    .onCancel(function() {
        console.log('Order cancelled. Removing line.');
        // Removes the line from the chart
        this.remove();
});
```

The callback registration methods (like [`onModify`], [`onCancel`]) are overloaded.
You can pass a single callback function, or you can pass a data object as the first argument and the callback as the second.
This data object will then be passed to your callback.

```javascript
// These are the static details of the order that your backend needs to identify it
const orderDetails = {
    avgPrice: 150,
    qty: 120,
};

// Create the order line on the chart
const orderLine = await widget.activeChart().createOrderLine();

orderLine
    .setQuantity("100")
    .setPrice(160)
    .setText("LIMIT BUY 100 @ 160.00")
    .onModify(orderDetails, function(data) {
        // 'this' refers to the orderLine object itself
        // 'data' is the orderDetails object we passed in

        // Set new price and quantity
        this.setPrice(data.avgPrice);
        this.setQuantity(data.qty);

        // Update the UI to give feedback to the user
        this.setText(`LIMIT BUY ${data.qty} @ ${data.avgPrice}`);
    });
```

Note that the buttons on an order or position line (e.g., *Modify*, *Cancel*, *Close*, *Reverse*) are displayed dynamically.
If you do not provide a callback for a specific action, its button is hidden from the UI.

## Customize appearance

You can set the default styles for order and position lines by using the [`trading_customization`] property in the [Widget Constructor].
For more information, refer to [Customize trading primitives](https://charting-library-docs.xstaging.tv/latest/customization/overrides/trading-overrides.md#created-with-trading-primitives).

### Styling reference

When customizing primitives, you can use the following formats for colors, fonts, and line styles:

#### Colors

- `#RGB`
- `#RRGGBB`
- `rgb(red, green, blue)`
- `rgba(red, green, blue, alpha)`

#### Fonts

You can use a string in the format: `<bold> <italic> <size>pt <family>`. For example, `"bold 12px Verdana"`.

#### Line Styles

Style|Value
---|---
Solid|0
Dotted|1
Dashed|2

[Broker API]: https://charting-library-docs.xstaging.tv/latest/trading_terminal/trading-concepts.md
[Trading Platform]: https://charting-library-docs.xstaging.tv/latest/trading_terminal.md
[Widget Constructor]: https://charting-library-docs.xstaging.tv/latest/configuration/Widget-Constructor.md

[`createOrderLine`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IChartWidgetApi#createorderline
[`createPositionLine`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IChartWidgetApi#createpositionline
[`createExecutionShape`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IChartWidgetApi#createexecutionshape
[`IChartWidgetApi`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IChartWidgetApi
[`onCancel`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IOrderLineAdapter#oncancel
[`onModify`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IOrderLineAdapter#onmodify
[`trading_customization`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.TradingTerminalWidgetOptions#trading_customization

---

## Sitemap

- [All documentation pages](https://charting-library-docs.xstaging.tv/llms.txt)
- [Full page map with headings](https://charting-library-docs.xstaging.tv/docs_map.md)