[Canonical page](<https://docs.dhtmlx.com/planning-engine/js/api/types/leveling-options/>)
[Full documentation index](<https://docs.dhtmlx.com/planning-engine/llms.txt>)


# LevelingOptions

Options for [`Project#level`](<https://docs.dhtmlx.com/planning-engine/js/api/project-level.md>), and the `level` option of [`Project#evaluate`](<https://docs.dhtmlx.com/planning-engine/js/api/project-evaluate.md>) and [`Project#suggestAssignments`](<https://docs.dhtmlx.com/planning-engine/js/api/project-suggest-assignments.md>). They set which part of the plan leveling acts on and how it may move tasks. Every field is optional: `{}` levels the whole project with default settings.

```ts
interface LevelingOptions {
  scope?: { resources?: Id[]; tasks?: Id[]; from?: DateValue; to?: DateValue };
  basis?: "hour" | "day";
  order?: "id" | "standard" | "priority";
  withinSlackOnly?: boolean;
  clearFirst?: boolean;
  allowSplits?: boolean;
  step?: "minimal" | "skip";
}
```

## Fields

| Field | Type | Default | Description |
|---|---|---|---|
| `scope` | object | whole project | Limits the run to some resources, tasks or dates. See [scope](<https://docs.dhtmlx.com/planning-engine/js/api/types/leveling-options.md#scope>). |
| `basis` | `"hour" \| "day"` | from `config.duration_unit` | Bucket size for detecting overallocation. Without it, the basis is `"day"` when `config.duration_unit` is `"day"`, and `"hour"` when it's `"hour"` or `"minute"`. |
| `order` | `"id" \| "standard" \| "priority"` | `"standard"` | Which contender gives way first. `"id"`: the task later in input order moves. `"standard"`: dependencies, slack, dates, `priority` and constraints, checked in that order. `"priority"`: lower `priority` moves first, then the `"standard"` rules apply. |
| `withinSlackOnly` | `boolean` | `false` | `true` caps each delay at the task's total slack. |
| `clearFirst` | `boolean` | `true` | `true` sets `leveling_delay: 0` and `pauses: []` on in-scope tasks before leveling. `false` keeps existing delays and pauses and levels on top of them. |
| `allowSplits` | `boolean` | `true` | `true` lets leveling write `pauses`. `false` allows whole-task delays (`leveling_delay`) only. |
| `step` | `"minimal" \| "skip"` | `"minimal"` | How far one move goes. `"minimal"`: just past the overallocated bucket. `"skip"`: past the whole overallocated window of the resource. |

The full rules behind `order`, `step` and `withinSlackOnly` are in [Leveling Resources](<https://docs.dhtmlx.com/planning-engine/js/resources-and-assignment/leveling-resources.md#selection-order>).

### scope

| Field | Type | Default | Description |
|---|---|---|---|
| `resources` | [`Id`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#id>)`[]` | every resource | Resources whose overallocation triggers a move. |
| `tasks` | [`Id`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#id>)`[]` | every task | Tasks leveling may delay or split; it writes no `leveling_delay` or `pauses` on other tasks. Also sets which tasks `clearFirst` clears. |
| `from` | [`DateValue`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#datevalue>) | start of the plan | Only buckets that start at or after `from` trigger a move. |
| `to` | [`DateValue`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#datevalue>) | end of the plan | Only buckets that start before `to` trigger a move. |

`from` and `to` limit where leveling looks for overallocation, not where moved tasks land: a task can end up past `to`. Overallocation outside the scope stays in the result's `overallocations` with `reason: "out-of-scope"`.

## Used by

- [`Project#level`](<https://docs.dhtmlx.com/planning-engine/js/api/project-level.md>): the `options` argument
- [`Project#evaluate`](<https://docs.dhtmlx.com/planning-engine/js/api/project-evaluate.md>): `options.level` levels each candidate with these options
- [`Project#suggestAssignments`](<https://docs.dhtmlx.com/planning-engine/js/api/project-suggest-assignments.md>): `options.level` scores candidates on the leveled stage

## Example

```js
const options = {
  scope: {
    resources: ["dev1"],
    from: "2026-08-10",
    to: "2026-08-24",
  },
  order: "priority",
  withinSlackOnly: true,
  allowSplits: false,
};
```

## Related

- [`Project#level`](<https://docs.dhtmlx.com/planning-engine/js/api/project-level.md>) - the call that takes these options
- [`Overallocation`](<https://docs.dhtmlx.com/planning-engine/js/api/types/overallocation.md>) - windows left after leveling and their `reason`
- [Leveling Resources](<https://docs.dhtmlx.com/planning-engine/js/resources-and-assignment/leveling-resources.md>) - how leveling works and what each option changes
- [Preview leveling](<https://docs.dhtmlx.com/planning-engine/js/how-to/preview-leveling.md>) - leveling a clone before committing
- [Clear leveling](<https://docs.dhtmlx.com/planning-engine/js/how-to/clear-leveling.md>) - removing delays and pauses