> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cristalyse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Create your first chart in 30 seconds

## Your First Chart in 30 Seconds

Let's create a beautiful scatter plot with just a few lines of code.

<Steps>
  <Step title="Import Cristalyse">
    Add the import to your Dart file:

    ```dart theme={null}
    import 'package:cristalyse/cristalyse.dart';
    import 'package:flutter/material.dart';
    ```
  </Step>

  <Step title="Prepare Your Data">
    Create a simple dataset:

    ```dart theme={null}
    final data = [
      {'x': 1, 'y': 2, 'category': 'A'},
      {'x': 2, 'y': 3, 'category': 'B'},
      {'x': 3, 'y': 1, 'category': 'A'},
      {'x': 4, 'y': 4, 'category': 'C'},
    ];
    ```
  </Step>

  <Step title="Build Your Chart">
    Create the chart with grammar of graphics:

    ```dart theme={null}
    CristalyseChart()
      .data(data)
      .mapping(x: 'x', y: 'y', color: 'category')
      .geomPoint(
        size: 8.0,
        alpha: 0.8,
        shape: PointShape.triangle,
        borderWidth: 1.5,
      )
      .scaleXContinuous()
      .scaleYContinuous()
      .theme(ChartTheme.defaultTheme())
      .build()
    ```
  </Step>
</Steps>

## Complete Example

Here's the full widget ready to use:

```dart theme={null}
import 'package:cristalyse/cristalyse.dart';
import 'package:flutter/material.dart';

class MyFirstChart extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final data = [
      {'x': 1, 'y': 2, 'category': 'A'},
      {'x': 2, 'y': 3, 'category': 'B'},
      {'x': 3, 'y': 1, 'category': 'A'},
      {'x': 4, 'y': 4, 'category': 'C'},
    ];

    return Scaffold(
      appBar: AppBar(title: Text('My First Chart')),
      body: Padding(
        padding: EdgeInsets.all(16.0),
        child: CristalyseChart()
          .data(data)
          .mapping(x: 'x', y: 'y', color: 'category')
          .geomPoint(
            size: 8.0,
            alpha: 0.8,
            shape: PointShape.triangle,
            borderWidth: 1.5,
          )
          .scaleXContinuous()
          .scaleYContinuous()
          .theme(ChartTheme.defaultTheme())
          .legend() // ✨ Add a legend to show categories
          .build(),
      ),
    );
  }
}
```

**Result:** A beautiful, animated scatter plot with color-coded categories!

<div align="center">
  <img src="https://mintcdn.com/cristalyse/PZSY86PoujCBYHYy/images/cristalyse_scatter_plot.png?fit=max&auto=format&n=PZSY86PoujCBYHYy&q=85&s=7a2d0293960081bb40d4e543794e7a7d" alt="Your First Chart Result" width="600" data-path="images/cristalyse_scatter_plot.png" />

  <br />

  <em>Your first chart - clean, responsive, and cross-platform</em>
</div>

## Formatting Axis Labels

You'll often want formatted axis labels.

The `labels` parameter takes any function that converts a number to a string:

```dart theme={null}
CristalyseChart()
  .data(salesData)
  .mapping(x: 'quarter', y: 'revenue')
  .geomBar()
  .scaleYContinuous(labels: (value) => '\$${value}') // $150
  .scaleXOrdinal()
  .build()
```

For robust, locale-aware formatting, use NumberFormat:

```dart theme={null}
import 'package:intl/intl.dart';

CristalyseChart()
  .data(salesData)
  .mapping(x: 'quarter', y: 'revenue')
  .geomBar()
  .scaleYContinuous(labels: NumberFormat.simpleCurrency().format) // $1,234.56
  .scaleXOrdinal()
  .build()
```

## Adding a Legend

<Tip>
  **New in v1.5.0**: Built-in legend support with zero configuration!
</Tip>

When your chart has color categories, add a professional legend with one line:

```dart theme={null}
final salesData = [
  {'quarter': 'Q1', 'revenue': 1000, 'product': 'ProductA'},
  {'quarter': 'Q2', 'revenue': 1200, 'product': 'ProductA'},
  {'quarter': 'Q1', 'revenue': 800, 'product': 'ProductB'},
  {'quarter': 'Q2', 'revenue': 950, 'product': 'ProductB'},
];

CristalyseChart()
  .data(salesData)
  .mapping(x: 'quarter', y: 'revenue', color: 'product') // Color mapping required
  .geomBar(style: BarStyle.grouped)
  .legend() // ✨ Automatically creates legend for each product
  .build();
```

**Key Benefits:**

* <Icon icon="target" /> **Zero Config**: Just add `.legend()` and it works
* <Icon icon="phone" /> **Smart Positioning**: Defaults to top-right, 8 position options available
* <Icon icon="moon" /> **Dark Mode Ready**: Text automatically adapts to theme colors
* <Icon icon="rotate-cw" /> **Auto-Symbols**: Squares for bars, circles for points, lines for line charts

<Info>
  **Requirement**: Legends need a `color` parameter in your `.mapping()` call to detect categories.
</Info>

### Quick Legend Positioning

```dart theme={null}
// Bottom legend (great for mobile)
.legend(position: LegendPosition.bottom)

// Right side legend
.legend(position: LegendPosition.right)

// Top-left corner  
.legend(position: LegendPosition.topLeft)
```

Learn more about [legend customization and styling](/features/legends).

## Understanding the Grammar

Cristalyse follows the **Grammar of Graphics** pattern:

<AccordionGroup>
  <Accordion title="Data" icon="database">
    `.data()` - Your dataset as a List of Map objects
  </Accordion>

  <Accordion title="Mapping" icon="palette">
    `.mapping()` - Connect data columns to visual properties (x, y, color, size)
  </Accordion>

  <Accordion title="Geometry" icon="square">
    `.geomPoint()`, `.geomLine()`, `.geomBar()` - How to visualize the data
  </Accordion>

  <Accordion title="Scales" icon="ruler">
    `.scaleXContinuous()`, `.scaleYContinuous()` - Transform data to screen coordinates
  </Accordion>

  <Accordion title="Theme" icon="paintbrush">
    `.theme()` - Colors, fonts, and visual styling
  </Accordion>
</AccordionGroup>