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


# PreviewOptions

Options for [`Project#preview`](<https://docs.dhtmlx.com/planning-engine/java/api/project-preview.md>). They set which part of the project is scheduled, which extra data the [`ScheduleResult`](<https://docs.dhtmlx.com/planning-engine/java/api/results/schedule-result.md>) carries, and which baseline the preview expects. Create one with `new PreviewOptions()` and set fields with the fluent `withX` setters. The defaults schedule the whole project and return only the changed tasks.

## Declaration

```java
public class PreviewOptions extends ValueRecord implements DeepCloneable<PreviewOptions>
```

## Constructors

### PreviewOptions()

```java
public PreviewOptions()
```

Creates options with every field at its default.

## Fields

| Field | Type | Default | Description |
|---|---|---|---|
| `subtree` | [`Subtree`](<https://docs.dhtmlx.com/planning-engine/java/api/project/subtree.md>) | `null` | Limits scheduling to one task's branch. `null` schedules the whole project. |
| `analytics` | [`AnalyticsOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/project/analytics-options.md>) | `new AnalyticsOptions()` (none requested) | Requests slack and the critical path. Fills [`ScheduleResult.analytics`](<https://docs.dhtmlx.com/planning-engine/java/api/results/schedule-result.md>). |
| `reasons` | `boolean` | `false` | Fills [`Mutation.reason`](<https://docs.dhtmlx.com/planning-engine/java/api/results/mutation.md>) on each update. |
| `baselineId` | `String` | `null` | The baseline the preview expects. `null` skips the check. |
| `profile` | [`ProfileQuery`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/profile-query.md>) | `null` | Requests a load profile of the previewed dates. Fills [`ScheduleResult.profile`](<https://docs.dhtmlx.com/planning-engine/java/api/results/schedule-result.md>). |

### subtree

```java
public Subtree subtree = null;
```

Limits scheduling to the scope that the [`Subtree`](<https://docs.dhtmlx.com/planning-engine/java/api/project/subtree.md>) value describes. Build the value with `new Subtree(id)`.

### analytics

```java
public AnalyticsOptions analytics = new AnalyticsOptions();
```

Turns on [`AnalyticsOptions.slack`](<https://docs.dhtmlx.com/planning-engine/java/api/project/analytics-options.md>) and [`AnalyticsOptions.criticalPath`](<https://docs.dhtmlx.com/planning-engine/java/api/project/analytics-options.md>) for the previewed dates. With both flags `false` (the default), `ScheduleResult.analytics` is `null`. With either flag set, it holds an [`Analytics`](<https://docs.dhtmlx.com/planning-engine/java/api/results/analytics.md>) value. Check its `status` before reading the data.

### reasons

```java
public boolean reasons = false;
```

When `true`, each [`Mutation`](<https://docs.dhtmlx.com/planning-engine/java/api/results/mutation.md>) in `ScheduleResult.updates` carries a [`Reason`](<https://docs.dhtmlx.com/planning-engine/java/api/results/reason.md>) in its `reason` field. When `false`, `reason` is always `null`.

### baselineId

```java
public String baselineId = null;
```

A baseline token taken from the latest [`ScheduleResult.baselineId`](<https://docs.dhtmlx.com/planning-engine/java/api/results/schedule-result.md>). When it isn't `null` and doesn't name the project's current baseline, [`Project#preview`](<https://docs.dhtmlx.com/planning-engine/java/api/project-preview.md>) throws a [`ProjectException`](<https://docs.dhtmlx.com/planning-engine/java/api/errors/project-exception.md>) with code `STALE_BASELINE`. It stops a preview from running over a baseline that changed underneath the UI.

[`SchedulingChanges.baselineId`](<https://docs.dhtmlx.com/planning-engine/java/api/changes/scheduling-changes.md>) is checked the same way, independently of this field.

### profile

```java
public ProfileQuery profile = null;
```

When set, `ScheduleResult.profile` holds the [`LoadProfile`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/load-profile.md>) of the previewed dates over the range and resources that the [`ProfileQuery`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/profile-query.md>) describes. When `null`, `ScheduleResult.profile` is `null`. An invalid query makes `Project#preview` throw an [`InputException`](<https://docs.dhtmlx.com/planning-engine/java/api/errors/input-exception.md>).

## Methods

### withSubtree, withAnalytics, withReasons, withBaselineId, withProfile

```java
public PreviewOptions withSubtree(Subtree value)
public PreviewOptions withAnalytics(AnalyticsOptions value)
public PreviewOptions withReasons(boolean value)
public PreviewOptions withBaselineId(String value)
public PreviewOptions withProfile(ProfileQuery value)
```

Each setter assigns its field and returns this instance for chaining.

**Returns** - this `PreviewOptions`.

### deepClone

```java
public PreviewOptions deepClone()
```

Returns a copy that shares no nested object (`subtree`, `analytics`, `profile`) with this instance.

**Returns** - a new `PreviewOptions` with the same values.

### copy

```java
public PreviewOptions copy()
```

Returns a shallow copy. The copy shares the `subtree`, `analytics` and `profile` objects with this instance.

**Returns** - a new `PreviewOptions` with the same field values.

### equals, hashCode, toString

```java
public boolean equals(Object other)
public int hashCode()
public String toString()
```

Inherited from [`ValueRecord`](<https://docs.dhtmlx.com/planning-engine/java/api/support/value-record.md>). Two `PreviewOptions` are equal when their public fields are equal. `toString()` lists the fields in the form `PreviewOptions{field=value, …}`.

## Example

```java
import java.util.List;
import org.dhtmlx.plen.*;

public class PreviewWithOptions {
  public static void main(String[] args) throws Exception {
    Moment monday = Moment.fromYmdHm(2026, 1, 5, 8, 0);
    Moment wednesday = Moment.fromYmdHm(2026, 1, 7, 8, 0);
    Moment nextMonday = Moment.fromYmdHm(2026, 1, 12, 8, 0);

    ProjectData data = new ProjectData()
        .withTasks(List.of(
            new TaskData(Id.str("design")).withStartDate(monday).withDuration(2.0),
            new TaskData(Id.str("build")).withStartDate(monday).withDuration(3.0)))
        .withLinks(List.of(
            new LinkData().withId(Id.str("l1")).withSource(Id.str("design")).withTarget(Id.str("build"))));

    Project project = new Project();
    ScheduleResult solved = project.solve(data, new SolveOptions());

    // The user drags "design" to Wednesday.
    SchedulingChanges changes = new SchedulingChanges();
    changes.tasks.update.add(new TaskUpdate(Id.str("design")).withStartDate(Patch.of(wednesday)));

    PreviewOptions options = new PreviewOptions()
        .withReasons(true)
        .withBaselineId(solved.baselineId)
        .withProfile(new ProfileQuery(monday, nextMonday));

    ScheduleResult preview = project.preview(changes, options);
    for (Mutation update : preview.updates) {
      // design: 2026-01-07 08:00 - 2026-01-09 08:00 (Preferred{})
      // build: 2026-01-09 08:00 - 2026-01-14 08:00 (Asap{linkId=l1, sourceId=design})
      System.out.println(update.id + ": " + update.startDate + " - " + update.endDate + " (" + update.reason + ")");
    }
  }
}
```

## Related

- [`Project#preview`](<https://docs.dhtmlx.com/planning-engine/java/api/project-preview.md>) - the call that takes it
- [`Subtree`](<https://docs.dhtmlx.com/planning-engine/java/api/project/subtree.md>) - limits the preview to one branch
- [`AnalyticsOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/project/analytics-options.md>) - slack and critical path switches
- [`ProfileQuery`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/profile-query.md>) - the load profile of the previewed dates
- [Previewing changes](<https://docs.dhtmlx.com/planning-engine/java/live-projects/previewing-changes.md>) - baseline tokens and preview with load