Step

Step breaks a long task with a clear sequence into manageable stages. Each step has its own title, status, and content area for Forms, inputs, instructions, and action buttons.

After reading this guide, you will be able to:

• Add a Step container and multiple StepItems
• Configure horizontal, vertical, navigation, and compact appearances
• Use default numbering and automatic status icons, or configure a consistent set of business icons
• Combine forms and buttons inside each step
• Use component functions to move forward, go back, jump, and reset
• Validate a form before switching and read the current step in onChange

Step, Tab, and Progress serve different purposes. Step represents tasks that must or should be completed in sequence. Tab organizes parallel content about the same object. Progress shows only a completion ratio and does not contain page content for each stage.

1. Example: campaign launch wizard

The Step page in Spark Sample uses a four-step campaign launch wizard:

Step	Content	What it demonstrates
Campaign details	Campaign name, owner, launch date, and summary	Two-column Form, required validation, full-row TextArea
Audience & budget	Audience, channels, budget, and conversion target	Back, Next, and numeric fields
Review	Read-only summary of the first two steps	Shared page state across steps and submission feedback
Submitted	Campaign number and completion message	Finished state and wizard reset

This example does not require a backend endpoint. Buttons switch steps through the Step component API, making the structure and Interaction easy to understand. To submit real data, add Send Request to the Review step's button interaction.

2. Add a Step container

1. Open the target page in Page Designer.
2. Expand Containers in the component palette.
3. Drag Step into Screen or another area that accepts containers.
4. Select Step and add StepItems under Steps.
5. Select each StepItem and enter its Title.
6. Add a Form, Panel, or input components to the StepItem content area.

Step and StepItem form a two-level structure:

Step
├── Campaign details
│   └── Form + Next button
├── Audience & budget
│   └── Form + Back / Next buttons
├── Review
│   └── Read-only Form + Back / Submit buttons
└── Submitted
    └── Result Form + Reset button

The child list supports drag-and-drop ordering. Reordering StepItems also updates their numbers and the forward/backward sequence.

3. Configure the Step container

Select the outer Step to configure:

Property	Values	Description
Initial Step	Integer starting at 1	Step shown when the page first opens; out-of-range values are clamped to the first or last step
Direction	horizontal, vertical	Arrange step headers horizontally or vertically
Step Style	default, navigation, inline	Standard flow, navigation flow, or compact inline style
Marker Size	small, medium, large	Controls the size of all numbers or icons; default is Medium
Label Placement	horizontal, vertical	Place the title to the right of or below the icon
Progress Dots	On / Off	Replace numbers or icons with dots; titles use vertical placement when enabled
Allow Step Click	On / Off	Let end users switch by clicking a step header
Show Step Content	On / Off	Show the current StepItem content area
Responsive	On / Off	Switch to a readable vertical layout on narrow screens
Current Step Status	process, wait, finish, error	Default status of the current step
Current Step Progress	0–100	Optional progress within the current step, mainly for Default + Process

3.1 Step styles

• Default: Best for standard form wizards, with the clearest relationship between status and sequence.
• Navigation: Makes the header resemble process navigation and suits flows where users may return to completed steps.
• Inline: A compact choice for limited space and short titles. With Vertical Direction, it falls back to Default to avoid an unreadable combination.

If the flow must be completed in order, turn off Allow Step Click and keep only Back, Next, and Submit buttons in the content area.

4. Configure StepItem

Select a StepItem to configure:

Property	Description
Title	Required primary title; use 2–5 words
Subtitle	Supporting information such as stage, estimated time, or owner
Description	Brief explanation of the current step
Status	auto, wait, process, finish, error
Disabled	Prevent clicking or component-function navigation to this step
Icon	Optional. Select a system icon with foreground/background colors or upload a custom image through the shared Icon picker

With Status set to auto, the system derives status from the current position: preceding steps are Finish, later steps are Wait, and the current item uses Current Step Status from Step. Override a StepItem only when an error, wait, or special finished state must remain visible.

4.1 Numbers, status, and business icons

Without an Icon, Step displays 1, 2, 3..., the recommended style for form wizards and approval flows. A completed step automatically replaces its number with a check mark. Current, waiting, and error states also receive the correct colors and markers automatically, so you do not need to configure red, yellow, or green backgrounds per step.

Add icons only when they clearly identify business stages, such as User, Document, Payment, Review, Send, or Milestone. Configure icons consistently for the whole group; do not mix numbered steps and icon steps. The Icon picker provides search, selected preview, foreground color, background color, and no-background options. The property panel shows the selected icon's name and identifier.

Marker Size belongs to the outer Step and keeps all numbers and icons consistent. Do not upload differently sized images to make one step visually heavier.

Edit different steps in the designer

In Design Mode, click a number or title in the step bar to switch the step being edited. The content area below shows the Form, Panel, inputs, and buttons owned by that StepItem; the property panel also switches to that StepItem.

Allow Step Click and StepItem Disabled control the saved page's runtime behavior. They do not prevent authors from opening a step in the designer. You can also expand Steps → StepItem → Form in the page structure and select a Form or field in a later step directly.

Use Disabled when a step's conditions are not yet satisfied. Next and Previous skip disabled steps automatically. If a step does not apply to the current user at all, hide it with the common display condition instead of merely disabling it.

5. Organize forms in steps

Add a Form to StepItem first, then place fields and ButtonSet inside it:

1. Form centrally controls Controls Per Row, Layout, Label Alignment, and the label/content ratio.
2. Form owns field validation; Step only controls process navigation.
3. Give every intermediate step a clear Next button; from the second step onward, also provide Back.
4. Use the last business step for Review and Submit, then move to a separate result step after submission.

The sample Form uses Controls Per Row = 2 and Label 4 / Content 8. Campaign summary enables Display Full Row. Its Label still occupies 4 columns and aligns with Launch date, while Content automatically uses the remaining row width.

When several steps need the same value, use the same field Name. For example, both the editing field and the Review read-only field use campaignName, so Review displays the latest value entered in the first step.

6. Configure forward, back, and reset

Step provides four component functions:

Function	Parameter	Behavior
nextStep	None	Move to the next available step, skipping Disabled items
previousStep	None	Return to the previous available step, skipping Disabled items
goToStep	stepNumber	Jump to a specific step; numbering starts at 1
resetSteps	None	Return to Initial Step

For the first step's Next button:

1. Select the button and open Interaction.
2. Under onClick, add Trigger Form Validation first and select campaign_details_form as Form.
3. Add a Component API action.
4. Select campaign_steps as Target Component.
5. Select nextStep as Function.

Actions run from top to bottom. If validation fails, nextStep does not run. The wizard advances only after validation succeeds.

The Back button only needs previousStep. The “Create another campaign” button on the completion page calls resetSteps.

7. Configure step-switch interactions

Step supports two interaction levels:

1. onChange on the outer Step.
2. onClick on an individual StepItem.

Before switching, the target step is written to the step context:

step.id
step.index
step.number
step.previousIndex
step.previousNumber
step.name
step.description
step.status

index starts at 0 for expression calculations. number starts at 1, matching the property panel and the number shown to users.

When a user clicks a step header, that StepItem's onClick runs first. After the step actually changes, the outer Step's onChange runs. Switching through Next, Previous, Go to, or Reset runs the outer onChange but does not treat programmatic navigation as a StepItem click. Disabled steps neither switch nor run interactions.

For example, add a Toast to Step onChange:

Now viewing step [[step.number]]: [[step.name]]

8. Scenario one: stay on the current step after backend validation fails

Step Validation Gate is a two-step sample. Step 1 starts with the invalid approval code TRY-AGAIN. The backend rejects the first submission and Step 1 remains active. Replace it with APPROVE-2026; only a successful response advances to Step 2.

1. Create Submit request and Accepted StepItems. Set Initial Step to 1 and turn off Allow Step Click.
2. Add requestTitle and approvalCode to a Form whose ID is validation_gate_form.
3. On Submit and continue, add Submit Form first. Use Custom URL /spark/api/sample/step/validation-gate and select validation_gate_form.
4. Add a component function after it: target validation_gate_steps and call nextStep.

Action order controls the flow. An HTTP error or success: false interrupts the chain, so nextStep does not run. Never place nextStep before the submit action.

if (!StringUtils.equals("APPROVE-2026", StringUtils.trim(request.getApprovalCode()))) {
    throw new LatticeRuntimeException(Message.code("SPARK-SAMPLE-STEP-0003"));
}

The complete reference is in StepWorkflowSampleController, StepWorkflowSampleService, and step-validation-gate-page.json in spark-sample.

9. Scenario two: open the current assignee's step from backend state

Step Handoff models two people working in sequence. Avery Chen has completed Step 1 and Morgan Lee owns Step 2. When Morgan opens the page, Page onLoad reads workflow state and opens Step 2. Allow Step Click stays enabled so Morgan can review the read-only Step 1.

1. Create Requester submission and Manager review StepItems. Keep Initial Step at 1 as the safe fallback, enable Allow Step Click, and make the completed first Form read-only.
2. On Page onLoad, send GET /spark/api/sample/step/handoff/status with caseId=CAM-2048.
3. Bind response activeStep to workflow.activeStep. You may also bind completion and assignee fields for status text.
4. Add a component function after the request: target handoff_steps, call goToStep, and bind stepNumber to workflow.activeStep.

Page onLoad
├── Send Request: GET /spark/api/sample/step/handoff/status
│   └── activeStep → workflow.activeStep
└── handoff_steps.goToStep([[workflow.activeStep]])

Runtime keeps the loading state until onLoad finishes, avoiding a visible jump from Step 1 to Step 2. If the request fails, the action chain stops and Initial Step remains active. The backend must calculate state and permissions for the signed-in user: activeStep controls presentation, not authorization.

10. Submit to a backend

The sample has no backend dependency to keep it easy to learn. In a real application, configure the Review Submit button in this order:

1. Trigger Form Validation.
2. Send Request or Submit Form.
3. Success Toast.
4. Call nextStep to enter the completion page.

Page requests automatically carry the current environment and render mode. Do not add protocol headers manually in Step. See Page request context and backend debugging for the full protocol.

If Send Request fails, stop later actions and keep the current step so the user can correct the data and retry. Do not enter the completion page before waiting asynchronously for the submission result.

11. Reproduce the Spark Sample

1. Add Step and set Horizontal, Default, Vertical Label, Responsive, and Allow Step Click.
2. Set Marker Size to Medium and keep the default number markers.
3. Add Campaign details, Audience & budget, Review, and Submitted StepItems without Icons.
4. Add a two-column Horizontal Form to the first three steps and a one-column read-only Form to the last step.
5. Make the first two Next buttons validate the current Form before calling nextStep.
6. Make the Back buttons in steps two and three call previousStep.
7. Make Review Submit show a success Toast and then call nextStep.
8. Make the Submitted reset button call resetSteps.
9. Save the page and complete the entire flow once in Preview and once at runtime.

For the advanced scenarios, use step-validation-gate-page.json and step-handoff-page.json. They are separate pages so action interruption and load-time positioning remain easy to inspect.

12. Troubleshooting

12.1 Next does not change the step

Check that:

• Target Component is the outer Step.
• Function is nextStep.
• The remaining steps are not all Disabled or hidden.
• An earlier Trigger Form Validation is not stopping because a required field is empty.
• The page is saved and runtime uses the current versionId.

12.2 Clicking a step header does nothing

Confirm Allow Step Click is enabled and the target StepItem is not Disabled. Disabling direct clicks is common in controlled flows; use content-area buttons in that case.

12.3 Review does not show previously entered values

Make sure the editing fields and Review read-only fields use the same stable Name. Display Name only changes the UI title and cannot share page state.

12.4 Step status differs from expectations

Normally, keep StepItem Status at auto. A manually configured Finish or Error overrides automatic derivation. Change it back to Auto to follow the current step again.

12.5 The page does not open the step returned by the backend

Check that Page has an onLoad event, the response binding writes workflow.activeStep, goToStep.stepNumber reads that path, and the backend returns a valid one-based integer. A failed Send Request intentionally stops the jump.

12.6 Steps are cramped on mobile

Enable Responsive and avoid long Title, Subtitle, and Description text. If mobile remains hard to read, use Vertical Direction or reduce the amount of visible text.

13. Design recommendations

• Keep a wizard to 3–7 steps. For more than 7, consider multiple pages or groups.
• Use outcomes or business stages as titles, such as Details, Audience, and Review; avoid full sentences.
• Label Next buttons with the destination, such as “Next: Review”, instead of a vague “Continue”.
• Turn off Allow Step Click for flows that prohibit skipping, and advance only after each step validates successfully.
• Provide Review before submission and a separate completion page afterward; do not rely only on a brief Toast.
• Give Error, Disabled, and completed states readable explanations instead of relying on color alone.