SciChart.js JavaScript 2D Charts API > The SciChartSurface (Root Chart Control) > The SciChartSurface Type
The SciChartSurface Type

Are you new to SciChart? Check out our most popular pages to get started below:

The basics of the SciChartSurface Type

The root 2D chart view is called the SciChartSurface. This is the JavaScript chart control you will be adding to your applications wherever you need a chart. You can add more than one SciChartSurface to an HTML page, you can configure them independently, and you can link them together.

The SciChartSurface has the following properties and functions which allow you to configure and control the chart. More info like this can also be found at the TypeDoc API Documentation for SciChart.

The SciChartSurface Type
Copy Code
export class SciChartSurface {
    /**
     * Creates a SciChartSurface and WebAssembly Context to occupy the div by element ID in your DOM.
     */
    public static create(divElementId: string, width: number = 0, height: number = 0): Promise<TWebAssemblyChart>;
    /**
     * Gets the collection of RenderableSeries - the chart types or seres on this SciChartSurface
     */
    public readonly renderableSeries: ObservableArray<IRenderableSeries>;
    /**
     * Gets the collection of Annotations - markers or shapes drawn over the top of a SciChartSurface
     */
    public readonly annotations: ObservableArray<IAnnotation>;
    /**
     * Gets the collection of AxisBase2D - the X Axis on a SciChartSurface
     */
    public readonly xAxes: ObservableArray<AxisBase2D>;
    /**
     * Gets the collection of AxisBase2D - the Y Axis on a SciChartSurface
     */
    public readonly yAxes: ObservableArray<AxisBase2D>;
    /**
     * An ObservableArray of IChartModifierBase derived types. Chart Modifiers provide behavior such as zooming, panning,
     * tooltips, legends and more in SciChart
     */
    public readonly chartModifiers: ObservableArray<IChartModifierBase>;
    /**
     * An event handler which notifies its subsribers when a render operation has finished. Use this
     * to time render performance, or to update elements of the chart or your UI on redraw.
     */
    public rendered: EventHandler<void> = new EventHandler<void>();
    /**
     * Applies a theme (defined by IThemeProvider) to the current element
     */
    public applyTheme(themeProvider: IThemeProvider);
    /**
     * Call invalidateElement() to trigger a redraw of the SciChartSurface. SciChart's WebGL WebAssembly rendering
     * engine will schedule a redraw a the next time the renderer is free.
     */
    public invalidateElement();
    /**
     * Deletes native (WebAssembly) memory used by this type, after which it cannot be used.
     */
    public delete(): void;
    /**
     * Gets the XAxis which matches the axisId. Returns undefined if not axis found
     */
    public getXAxisById(axisId: string);
    /**
     * Gets the YAxis which matches the axisId. Returns undefined if not axis found
     */
    public getYAxisById(axisId: string);
    /**
     * Zooms the SciChartSurface in the X and Y direction to extents of all data (zoom to fit)
     */
    public zoomExtents(animationDurationMs: number = 0, easingFunction: TEasing = easing.outExpo);
    /**
     * Zooms the SciChartSurface in the X direction to extents of all data (zoom to fit)
     */
    public zoomExtentsX(animationDurationMs: number = 0, easingFunction: TEasing = easing.outExpo);
    /**
     * Zooms the SciChartSurface in the Y direction to extents of all data (zoom to fit)
     */
    public zoomExtentsY(animationDurationMs: number = 0, easingFunction: TEasing = easing.outExpo);
}

Series or Chart Types

SciChartSurface has collections of RenderableSeries (see sciChartSurface.renderableSeries), which form the series or chart types on the chart. Each RenderableSeries must have a DataSeries (see DataSeries types) which defines the data for that chart type.

Several RenderableSeries types are available in SciChart, including

For more information about chart types in SciChart, head over to the RenderableSeries API documentation or see our Examples.

Axis and Axis Types

SciChartSurface has a collection of X-Axis and Y-Axis (see sciChartSurface.xAxes collection). Each SciChartSurface can have unlimited, multiple X and Y Axis. SciChart is unique in that you can place axis on the left, right, top, bottom, but you can also rotate the chart to have an XAxis on the left and YAxis on the top. It is this configurability which gives SciChart it's edge over other charting libraries.

A few axis types are available in SciChart, such as Value Axis and Category Axis. Axis may be configured by setting gridline interval, gridline styling, titles, labels and more.  

For more information about Axis types and configuration in SciChart, head over to the Axis API documentation or see our Examples.

Annotations and Markers

SciChartSurface has a collection of Annotations (see sciChartSurface.annotations collection). Annotations are markers (text, labels, lines, custom shapes) which can be placed arbitrarily over the chart (see types of annotation here), independent of chart types (series) or data. As the chart zooms and pans, the annotations move with the chart, however there is also an xCoordinateMode and yCoordinateMode property on Annotations which allows you to place watermarks, or dock annotations to the left, right, top, bottom or centre of a chart.

For more information about Annotations types in SciChart, head over to the Annotations API documentation or see our Examples.

Interaction - Zooming, Panning and Tooltips

Zooming, Panning, interaction such as Tooltips and Legends are provided by ChartModifiers. Several modifiers exist out of the box such as the ZoomPanModifierRubberBandXyZoomModifier and MouseWheelZoomModifier. Tooltips and Legends are also provided by modifiers - see the RolloverModifier and LegendModifier. You can also create your own modifiers and handle mouse interactions and provide custom behaviours to the chart using this powerful and flexible API.

For more information about Chart Modifier types in SciChart, head over to the ChartModifier API documentation or see our Examples.

Styling and Themeing

All SciChart chart parts including the SciChartSurface, Axis, Tooltips and more can be styled and themed. SciChart ships with a Light Theme and Dark Theme out of the box. You can customize the colours of a chart to fit the overall style of your application.

For more information about Styling and Themeing in SciChart, head over to the Section on Styling in our documentation or see our Examples.

 

Declaring a SciChartSurface Instance

In Tutorial #1 - Setting up a Project with SciChart.js, we walk you through how to setup a new project with npm, webpack and install SciChart. In particular we show you how to copy the wasm files to the build output, a step that is necessary for our WebAssembly WebGL powered charts.

If you haven't already, go and watch that tutorial quickly so that you can understand the basics of setting up a project with SciChart. The tutorial series is a great way to learn SciChart.

We also have a comprehensive Examples Suite with many examples of how to use our Fast, JavaScript Charts.