States and indicators

This page outlines the key states used across the Adapt framework and the visual indicators that communicate them to learners. It serves as a conceptual reference for framework and plugin developers.

Priority

'Priority' describes whether content is optional or required. It applies to menus, pages, articles, blocks and components.

Name	Description
Optional	Content does not need to be completed to mark the parent or tracking criteria complete.
Required	Content needs to be completed to mark the parent or tracking criteria complete.

The key model attribute is _isOptional.

Current indicators

• Page Level Progress "Optional Content" text
• Priority labels - Configurable per content type (menu item shown below)

Screenshots

PLP drawer showing 'Optional content' label on an item


Menu item with 'optional' badge label

Configuring optional content

{
  "_type": "block",
  "_isOptional": true
}

Locked

Items which should not yet be accessed or which have criteria to unlock them can be considered 'locked'.

Name	Description
Locked	The criteria have not been met to view this content.
Unlocked	Pseudo status with no existing meaning.

The key model attribute is _isLocked, controlled via _lockType. See Locking objects with '_isLocked' and '_lockType' for configuration details.

Current indicators

A locked icon and/or a disabled state is used to signify that something is locked:

• Trickle buttons
• Page Level Progress items
• Menu items

Screenshots

Locked Trickle button beneath a Narrative component


Locked menu item with padlock icon

Visited

'Visited' is typically used to show that some of a page's children have been interacted with or that a component item has been selected.

Page visited has two potential modes:

1. The page was opened in this session
2. The page was restored and some of its descendants were completed or visited

Current indicators

• Menu progress bars showing more than the minimum notch
• Component items showing highlighted and/or ticked where supported

Where a component supports both Visited and Selection, the visited indicator persists after interaction (e.g. a ticked accordion item), while the selection indicator reflects the currently active item.

Screenshots

Menu showing a progress bar with a partial notch, indicating some content has been visited

Selection

'Selection' signifies that a user has chosen a subset of options from a visible list. It is the common term for the _isActive status of the ComponentItemModel and ItemModel code.

Name	Description
Selected	The user has chosen this item.
Not Selected	The user has not chosen this item.

Current indicators

• MCQ radio and checkboxes, either unfilled or filled
• GMCQ highlighting
• Hot Graphic pagination
• Accordion highlighting / expansion
• Narrative indicator highlighting
• Matching highlighting / dropdown
• Slider handle
• Text input cursor

Screenshots

MCQ with one radio selected and others unselected


Accordion with one item highlighted/expanded

Completion

'Completion' usually denotes that a component, item or page has been interacted with in totality.

Completion is subject to the 'priority' of its children (blocks to articles, items to components, etc) and the rules governing their completion, such as inview states, item visited states, _requireCompletionOf, correctness criteria, branching ends etc.

Completion can also refer to the fulfillment of the course tracking criteria — a course is said to be complete at its conclusion.

Completion applies to menus, pages, articles, blocks and components. For presentation component items, completion is usually called _isVisited.

Name	Description
Complete	The content has been fully interacted with.
Incomplete	The content has not yet been fully interacted with.

The key model attributes are _isComplete and _isInteractionComplete.

Current indicators

• Page Level Progress bars — unfilled, partly filled or filled — on menu items, the navigation bar, drawer items and title asides
• Question marking icon (tick or cross) appears between the question buttons on completion (symbol determined by correctness)
• Question action buttons disabled or hidden after final submission (Submit, Reset, Show correct answer)
• Question inputs disabled after final submission, preventing re-selection (radio buttons, checkboxes, dropdowns)
• Menu ticks
• Item visited ticks in Hot Graphic, Accordion, Media and Narrative
• Item visited highlighting in Accordion, Narrative

Screenshots

PLP drawer showing unfilled, partly filled, and fully filled completion bars


Completed question with marking icon indicating a correct answer


Menu item with a completion tick

Configuring PLP completion tracking

Page Level Progress tracks completion independently at article, block, and component level. Each level can be opted out by setting _pageLevelProgress._isEnabled: false on that content object — this removes it from the PLP drawer entirely, leaving its parent to represent the progress instead.

Branching content

In courses that use adapt-contrib-branching, learners follow one of several paths through an article. If PLP tracks at block or component level, the blocks on untaken branches may appear incomplete in the drawer — even though the learner completed a valid path.

The recommended approach is to disable PLP on the individual blocks within the branching article and let PLP track at article level. The branching plugin handles article completion automatically: when a learner reaches a branching endpoint, the article's completion is triggered regardless of which path was taken. PLP block-level opt-out must be configured by the course author.

{
  "_type": "block",
  "_pageLevelProgress": {
    "_isEnabled": false
  }
}

See the adapt-contrib-pageLevelProgress wiki for full configuration reference.

Correctness

'Correctness' is a sub-state of 'complete', such that something generally can't be wholly marked for correctness whilst being incomplete.

Correctness tends to apply to question components, question component items and assessments.

Component / item level

Name	Indicators
Correct	Tick on marking icon; feedback via Tutor; item marking on MCQ, GMCQ, Matching (if _canShowCorrectness is enabled)
Partly correct	Cross on marking icon; feedback via Tutor
Incorrect	Cross on marking icon; feedback via Tutor; item marking on MCQ, GMCQ, Matching (if _canShowCorrectness is enabled)

Screenshots

Tutor notify popup showing correct feedback


MCQ items marked with ticks and crosses after submission

Configuring correctness marking

Two properties control how correctness is displayed on a question component:

• _canShowMarking — shows a tick or cross on the question button (default true)
• _canShowCorrectness — shows tick/cross marking on individual items, e.g. MCQ options (default false); enabling this replaces the "show correct answer" toggle button

{
  "_component": "mcq",
  "_canShowMarking": true,
  "_canShowCorrectness": true
}

Assessment level

Assessment correctness tends to have more complex criteria than item and question correctness, such as score or the number of items correct thresholds.

Name	Description
Pass	The specified criteria have been met.
Fail	The specified criteria have not been met.

Correctness feedback includes

• Assessment results
• LMS completion/pass/fail status

Assessment Results component showing how the learner performed

Accessibility

Each state is conveyed to screen readers through translatable ARIA labels defined in _globals._accessibility._ariaLabels in course.json. See Globals and ARIA Labels for the full configuration reference.

State-specific labels

State	ARIA label key	Default text
Complete	complete	"Completed"
Incomplete	incomplete	"Incomplete"
Correct (announcement)	answeredCorrectly	"You answered correctly"
Partly correct (announcement)	answeredPartlyCorrect	"You answered partly correct"
Incorrect (announcement)	answeredIncorrectly	"You answered incorrectly"
Correct (marking)	correct	"Correct"
Partly correct (marking)	partlyCorrect	"Partly correct"
Incorrect (marking)	incorrect	"Incorrect"
Selected	selectedAnswer	"selected"
Not selected	unselectedAnswer	"not selected"
Locked	locked	"Locked"
Visited	visited	"Visited"
Optional	optionalContent (PLP)	"Optional content"
Required / Optional	required, optional (Priority labels)	"Required", "Optional"

Note: Correctness has two sets of labels. The "announcement" labels are used in aria-live regions when answers are submitted. The "marking" labels are used on tick/cross indicators alongside question items.

How states are communicated

• Composite aria-label attributes — Multiple state labels are combined into a single aria-label on elements like PLP items and menu items (e.g., "Locked. Module 1.").
• aria-disabled="true" — Applied alongside the locked label on menu items and PLP items to indicate non-interactive state.
• aria-live="assertive" regions — Used for dynamic state changes such as correctness feedback on question submission and show/hide correct answer toggling. See ARIA Roles and Labels for details.
• _isA11yCompletionDescriptionEnabled — Per-element toggle (default true) that controls whether completion state is announced for that element. Available on content objects, articles, blocks and components. See Core Model Attributes.

Configuring ARIA labels

To override the default text for any state label, add the key to _globals._accessibility._ariaLabels in course.json:

{
  "_globals": {
    "_accessibility": {
      "_ariaLabels": {
        "complete": "Finished",
        "locked": "Not yet available"
      }
    }
  }
}

See Globals and ARIA Labels for all available keys and their defaults.

Further reading

• ARIA Roles and Labels — aria-expanded, aria-haspopup, live regions
• Globals and ARIA Labels — Full _ariaLabels configuration
• Accessibility — WCAG 2.2 AA compliance overview