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

# Scales

A **scale** turns data values into visual values — a number into a pixel position, a category into a color, a magnitude into a point size. Every [aesthetic](/sdk-next/concepts/mappings) you map needs a scale to interpret it.

```tsx theme={null}
scale.x(); // infer an x-axis scale from the data
scale.y.continuous({ domainMin: 0 }); // an explicit continuous y-axis, pinned to zero
scale.color.discrete({ range: ['#4C6EF5', '#F76707'] });
```

## Position scales must be declared

**Position scales are never created automatically.** If you map `x` or `y`, you must add `scale.x()` / `scale.y()`. Miss one and that axis has no scale, producing `NaN` positions and a blank chart.

```tsx theme={null}
pipe(
  createSpec({ x: 'month', y: 'revenue' }),
  geom.line(),
  scale.x(), // required
  scale.y() // required
);
```

Visual scales (`color`, `size`, …) are more forgiving — a mapped `color` without an explicit scale falls back to the default palette — but declaring them keeps a chart predictable.

## Inference vs explicit types

Position scales are **callable** to infer their type from the mapped column's [value format](/sdk-next/data-structure#value-format-detection):

* text → **discrete** (band) scale
* number / percentage / currency → **continuous** scale
* date → **temporal** scale

```tsx theme={null}
scale.x(); // inferred
scale.x({ nice: true }); // inferred, with options
```

Or name the type explicitly when you want to force a treatment:

```tsx theme={null}
scale.x.continuous();
scale.x.discrete();
scale.x.datetime();
scale.x.log();
scale.x.sqrt();
```

## Scales by aesthetic

| Aesthetic                      | Methods                                                                                 |
| ------------------------------ | --------------------------------------------------------------------------------------- |
| `x`, `y`, `ySecondary`         | callable (inferred), `.continuous()`, `.discrete()`, `.datetime()`, `.log()`, `.sqrt()` |
| `color`                        | `.continuous()`, `.discrete()`, `.palette()`                                            |
| `size`, `alpha`, `strokeWidth` | `.continuous()`, `.discrete()`, `.identity()`                                           |
| `lineType`                     | `.discrete()`, `.identity()`                                                            |

### Color scales

```tsx theme={null}
scale.color.palette(); // Graphy's default palette
scale.color.discrete({ domain: ['A', 'B'], range: ['#4C6EF5', '#F76707'] }); // fixed colors
scale.color.continuous(); // a numeric gradient
```

### Identity scales

An identity scale passes data values straight through as visual values — `{ size: 10 }` becomes 10px, no transformation. Useful when your data already holds pixel sizes or CSS colors.

```tsx theme={null}
scale.size.identity();
```

## Continuous scale options

The continuous methods (and `.log()` / `.sqrt()`, which are continuous with a transform) accept:

<ParamField path="domainMin" type="number | null">
  Force the lower bound of the domain. `domainMin: 0` makes an axis start at
  zero.
</ParamField>

<ParamField path="domainMax" type="number | null">
  Force the upper bound of the domain.
</ParamField>

<ParamField path="nice" type="boolean">
  Extend the domain to round values — `[3, 97]` becomes `[0, 100]`.
</ParamField>

<ParamField path="zero" type="boolean">
  Include zero in the domain.
</ParamField>

<ParamField path="reverse" type="boolean">
  Reverse the direction of the scale.
</ParamField>

<ParamField path="transform" type="'linear' | 'log' | 'sqrt'">
  A mathematical transform applied to the scale. `scale.y.log()` is shorthand
  for `transform: 'log'`.
</ParamField>

## Discrete scale options

<ParamField path="domain" type="string[]">
  The categories, in the order they should appear. Omit to derive them from the
  data.
</ParamField>

<ParamField path="range" type="Array<string | number>">
  Explicit output values — colors, sizes, or dash patterns — aligned to
  `domain`.
</ParamField>

## Next

* [Coordinate systems](/sdk-next/concepts/coordinate-systems) — the plane scales place values into
* [Chart types](/sdk-next/graph-types/index) — scales at work in each recipe