# Scatter Chart

## Component Visuals

{% tabs %}
{% tab title="Overview" %}

<figure><img src="https://1173113760-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYEKIeE9xnHLXuuwEs8zo%2Fuploads%2FtQ06UfllYWquxM9Q96Tg%2FScatter%20Chart.png?alt=media&#x26;token=1c8042ef-847a-481b-b81a-5bafc3ac9889" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Visual 1" %}

<figure><img src="https://1173113760-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYEKIeE9xnHLXuuwEs8zo%2Fuploads%2Fnrb7aaz9xJL4hGHsPhay%2FScatter%20Chart%20v1.png?alt=media&#x26;token=f11f072f-0080-44f1-a373-d546cd242649" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Visual 2" %}

<figure><img src="https://1173113760-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYEKIeE9xnHLXuuwEs8zo%2Fuploads%2F77gDqBmbmiJnSljDZwgk%2FScatter%20Chart%20v2.png?alt=media&#x26;token=f726a84e-4595-4586-b8cc-c7e1f25ea104" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Visual 3" %}

<figure><img src="https://1173113760-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYEKIeE9xnHLXuuwEs8zo%2Fuploads%2FahaMZv4ualYZrnrI0F3Y%2FScatter%20Chart%20v3.png?alt=media&#x26;token=e2fc944b-a2d7-457d-bb39-b9a5be82720b" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

### Installation

To use the `Chart` component, you need to install the Quest Labs React SDK:

* Open your terminal/command prompt.
* Navigate to your project's root directory using the `cd` command if you're not already there.
* Run the following command to install the `quest-sdk` package using npm:

```bash
npm install @questlabs/react-graphs
```

> This command will download and install the package and its dependencies into your project.

*Note: The Quest Labs React Graph SDK includes ECharts as a dependency. When you install `@questlabs/react-graphs`, ECharts will be automatically installed as well. ECharts is a powerful charting library used by the Quest Labs SDK to render various types of charts, including the* `Chart.Scatter` *component.*

{% hint style="info" %}
Make sure your project has npm and Node.js installed, and that you have the necessary permissions to install packages in your project directory.
{% endhint %}

### Features

The `Chart.Scatter` component from Quest Labs SDK offers powerful features for creating interactive and visually appealing line charts in your React applications:

* **Theme Support:** Customize the appearance of the scatter chart using themes. Themes allow you to define colors, fonts, and other visual properties to match your application's design system.
* **Data-driven:** Visualize data easily with the `Chart.Scatter` component by providing an array of data points. Each data point consists of x and y coordinates, enabling you to display trends and patterns over time or other variables.
* **Tooltip Integration:** Easily add tooltips to display additional information when users hover over data points. Tooltips enhance interactivity and provide contextual details about data values.
* **Event Callbacks:** Utilize event callbacks such as `onChartLoad`, `onChartLoaded`, and `onChartInitialized` to handle chart loading states, data retrieval, and initialization. These callbacks help manage chart lifecycle events efficiently.
* **React Integration:** Built with React in mind, the `Chart.Scatter` component integrates smoothly into React applications. It leverages React's state management and component lifecycle methods for efficient data handling and rendering.

### Props

`Chart` component props

<table><thead><tr><th width="147">Prop Name</th><th width="152">Type</th><th>Required</th><th>Details</th></tr></thead><tbody><tr><td><strong>children</strong></td><td>JSX.Element | JSX.Element[]</td><td>No</td><td>The children components to be rendered inside the chart container.</td></tr><tr><td><strong>chartId</strong></td><td>string</td><td>No</td><td>The unique identifier for the chart. Generated through QuestApp.</td></tr><tr><td><strong>theme</strong></td><td>object</td><td>No</td><td>The theme configuration for the chart.</td></tr><tr><td><strong>data</strong></td><td>ScatterChartDataset[]</td><td>No</td><td>The dataset for the chart. Each data object should follow the <code>ChartDataset</code> type structure.</td></tr><tr><td><strong>setData</strong></td><td>function</td><td>No</td><td>The function to set the dataset. It can accept <code>SetStateAction</code> for various chart datasets.</td></tr><tr><td><strong>onChartInitialized</strong></td><td>function</td><td>No</td><td>Callback function invoked when the chart is initialized.</td></tr><tr><td><strong>onChartLoaded</strong></td><td>function</td><td>No</td><td>Callback function invoked when the chart data is loaded. Optional parameter for the loaded data.</td></tr><tr><td><strong>onChartLoad</strong></td><td>function</td><td>No</td><td>Callback function invoked when the chart starts loading.</td></tr><tr><td><strong>height</strong></td><td>string | number</td><td>No</td><td>The height of the chart container.</td></tr><tr><td><strong>width</strong></td><td>string | number</td><td>No</td><td>The width of the chart container.</td></tr></tbody></table>

`Chart.Scatter`component props

| Prop Name     | Type             | Required | Details                                                                                       |
| ------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------- |
| **legend**    | object           | No       | The configuration for the chart legend, including position, formatter, icon, and text styles. |
| **grid**      | object           | No       | The configuration for the chart grid, including position and label containment.               |
| **xAxis**     | Axis             | No       | The configuration for the x-axis, including type, visibility, formatter, and styles.          |
| **yAxis**     | Axis             | No       | The configuration for the y-axis, including type, visibility, formatter, and styles.          |
| **toolbox**   | object           | No       | The configuration for the toolbox component.                                                  |
| **tooltip**   | object           | No       | The configuration for the tooltip, including styles and alignment options.                    |
| **zoom**      | object           | No       | The configuration for zooming, including enabling wheel/slider zoom, start/end, and styles.   |
| **resizable** | boolean          | No       | Whether the chart is resizable.                                                               |
| **height**    | string \| number | No       | The height of the scatter chart container.                                                    |
| **width**     | string \| number | No       | The width of the scatter chart container.                                                     |

### Types

```typescript
type ScatterChartDataset = {
    id?: string;
    data: number[] | number[][];
    name?: string;
    cursor?: 'auto' | 'default' | 'pointer' | 'move' | 'text' | 'wait' | 'help' | 'not-allowed' | 'crosshair' | 'grab'| 'grabbing' | 'zoom-in' | 'zoom-out';
    extraData?: any;
    show?: boolean
    showSymbol?: boolean;
    symbolStyle?: ItemStyle<StyleWithGradient> & {
        type?: 'rect' | 'roundRect' | 'circle';
        size?: number | ((data: number | number[]) => number)
    };
    step?: 'start' | 'middle' | 'end';
    emphasis?: Style & {
        scale?: number;
        label?: any;
        focus?: 'none' | 'self' | 'series';
    };
    animationDelay?: number;
    animationDuration?: number;
    animationEasing?: "backIn" | "backInOut" | "backOut" | "bounceIn" | "bounceInOut" | "bounceOut" | "circularIn" | "circularInOut" | "circularOut" | "cubicIn" | "cubicInOut" | "cubicOut" | "quinticIn" | "quinticInOut" | "quinticOut" | "sinusoidalIn" | "sinusoidalInOut" | "sinusoidalOut" | "elasticInOut" | "elasticout" | "exponentialIn" | "exponentialInOut" | "exponentialOut" | "linear" | "quadraticIn" | "quadraticInOut" | "quadraticout" | "quarticIn" | "quarticInOut" | "quarticout";
}

type Axis = {
    type?: 'time' | 'category' | 'log' | 'value';
    show?: boolean;
    formatter?: string | ((param: string) => string);
    showSplitLine?: boolean;
    showAxisLine?: boolean;
    splitLineStyle?: LineStyle;
    axisLineStyle?: LineStyle;
    labelStyle?: FontStyle & TextBorderStyle & TextShadowStyle & {
        fontFamily?: string;
        fontSize?: number | string;
        fontWeight?: 'bold' | 'bolder' | 'lighter' | 'normal';
        fontStyle?: 'italic' | 'normal' | 'oblique';
        textBorderWidth?: number;
        textBorderColor?: string;
        textBorderType?: 'dashed' | 'dotted' | 'solid';
        textBorderDashOffset?: number;
        textShadowBlur?: number;
        textShadowColor?: string;
        textShadowOffsetX?: number;
        textShadowOffsetY?: number;
        margin?: number;
        align?: Align;
        verticalAlign?: 'bottom' | 'middle' | 'top';
        color?: string;
    },
    min?: number;
    max?: number;
    data?: string[] | number[];
    boundaryGap?: string | [string, string]
}
```

### Usage

To integrate the `Chart.Scatter` component into your React application, follow these steps

* **Import the CSS**: In your JavaScript or TypeScript file where you're using the `Chart.Scatter`, import the CSS styles for the component. This ensures that the component's styling is applied correctly.

```jsx
import '@questlabs/react-graphs/dist/style.css'
```

* **Import the Chart Component**: Import the `Chart`component from the `@questlabs/react-graphs` package.

```jsx
import { Chart } from '@questlabs/react-graphs';
```

## Example Usage

Here's an example of how to use the `Chart.Scatter`  component within your React application.

```typescript
import { Chart } from '@questlabs/react-graphs';
import type { ScatterChartDataset } from '@questlabs/react-graphs';
import '@questlabs/react-graphs/dist/style.css'

const scatterChartData: ScatterChartDataset[] = [
  {
    name: 'Online Sales',
    data: [-20, -40, -20, -40, -60, -40, -20],
    symbolStyle: {
      color: 'rgba(101, 37, 179, 1)'
    },
  },
  {
    name: 'Offline Sales',
    data: [0, 20, 0, -20, -40, -20, -20],
    symbolStyle: {
      color: 'rgba(144, 53, 255, 1)'
    },
  },
  {
    name: 'Hybrid Sales',
    data: [-40, -20, -40, 20, 0, 20, -40],
    symbolStyle: {
      color: 'rgba(163, 87, 255, 1)'
    },
  }
]

function App() {

  return (
    <div style={{display: 'grid', placeItems: 'center', height: '100vh', background: 'whitesmoke'}}>
      <Chart data={scatterChartData} style={{width: 400}}>
        <Chart.Header>
          <Chart.Title>
            Step Chart
          </Chart.Title>
          <Chart.Option onSelect={console.log}>
            <Chart.Item label="Last 90 days" value="LAST_90D" />
            <Chart.Item label="Last 90 days" value="LAST_90D" />
          </Chart.Option>
          <Chart.Info>
            This is my scatter chart component
          </Chart.Info>
        </Chart.Header>
        <div style={{ padding: '10px 20px', display: 'flex', gap: 10 }}>
          <Chart.DatePicker value="03-05-2020" label="Start Date" />
          <Chart.DatePicker value="03-05-2024" label="End Date" />
        </div>
        <Chart.Scatter xAxis={{ data: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul'] }}/>
        <Chart.Footer />
      </Chart>
    </div>
  );
}

```

You can fully customize the chart layout and use the `useChart<ChartContextSingleType>` hook provided by `@questlabs/react-graphs`. This hook provides various options.<br>

```typescript
type ChartContextSingleType<T extends ChartDataset> = {
    theme?: Record<string, string>;
    data: T[];
    setData: React.Dispatch<SetStateAction<T[]>>;
    loading: boolean;
    getChartId: () => string;
    setChartId: (chartId: string) => void;
    getQuery: () => string;
    setQuery: (queryString: string) => void;
    refetch: (props?: {chartId?: string, query?: string}) => Promise<T>;
    title?: string;
}
```

### Demo

Check a demo video for better understanding.

{% embed url="<https://drive.google.com/file/d/1nmqphzZDKPI1M0aZNhIknVJetpN4j-1Q/view?usp=sharing>" %}