Priority labels

‼️ This feature is not yet available. This page also will need to be updated with screenshots and plugin version numbers.

See https://github.com/adaptlearning/adapt-contrib-core/pull/817 for more information.

Priority Labels

Priority labels allow you to visually indicate which content is required or optional throughout your course. Labels can be displayed on menu items, pages, articles, blocks, and components.

Overview

By default, all content in Adapt is required for course completion unless marked as optional via the _isOptional setting. Priority labels make this distinction visible to learners by displaying "Required" or "Optional" labels alongside content headings.

Key features:

• Configure labels globally in course.json with per-content-type control
• Override global settings on individual elements
• Add custom icons to labels
• Style required and optional content differently via CSS classes

Common use cases:

• Compliance training where certain modules must be completed
• Learning paths with mandatory core content and optional enrichment
• Courses where learners need clear guidance on what they can skip

Plugin Version Requirements

Priority labels require the following minimum plugin versions:

• adapt-contrib-core: [VERSION_PLACEHOLDER]
• adapt-contrib-vanilla: [VERSION_PLACEHOLDER] (for default styling)
• adapt-contrib-boxMenu: [VERSION_PLACEHOLDER] (if using Box Menu)

Other menu plugins will need updates to support priority labels on menu items.

Configuration

Global Configuration

Add the _priorityLabels object to _globals in your course.json. This controls the display of labels across all content types.

"_globals": {
  "_priorityLabels": {
    "_iconClassOptional": "",
    "_iconClassRequired": "icon-exclamation",
    "_menuItem": {
      "_showWhenOptional": true,
      "_showWhenRequired": false
    },
    "_page": {
      "_showWhenOptional": true,
      "_showWhenRequired": false
    },
    "_article": {
      "_showWhenOptional": false,
      "_showWhenRequired": false
    },
    "_block": {
      "_showWhenOptional": false,
      "_showWhenRequired": false
    },
    "_component": {
      "_showWhenOptional": false,
      "_showWhenRequired": false
    }
  }
}

Configuration Properties

_iconClassOptional (string) CSS class for the icon shown on optional content (e.g., "icon-info"). Leave empty for no icon.

_iconClassRequired (string) CSS class for the icon shown on required content (e.g., "icon-exclamation"). Leave empty for no icon.

_menuItem, _page, _article, _block, _component (object) Configuration for each content type with the following properties:

• _showWhenOptional (boolean): Display the "Optional" label when _isOptional: true
• _showWhenRequired (boolean): Display the "Required" label when _isOptional: false

Per-Element Override

You can override global settings on any individual element (content objects, articles, blocks, or components):

"_priorityLabels": {
  "_isOverride": true,
  "_showWhenRequired": true,
  "_showWhenOptional": false
}

This is useful when you want different behavior for specific items. For example, you might disable labels globally for blocks but show them for one important block.

Marking Content as Optional

To mark content as optional, set _isOptional: true on the element:

"_isOptional": true

This property is available on content objects (menus/pages), articles, blocks, and components.

How It Works

Priority labels only appear when:

1. A displayed title (displayTitle) is present on the element
2. The content type has labels enabled in configuration
3. The element meets the optional/required criteria for display

The framework automatically:

• Reads the global configuration from _globals._priorityLabels
• Checks if the element has a local override via _priorityLabels._isOverride
• Determines if the element is optional via _isOptional
• Sets appropriate CSS classes: is-priority-required or is-priority-optional
• Passes label data to templates for rendering

Label Text Customization

The label text comes from the accessibility labels defined in _globals._accessibility._ariaLabels:

"_accessibility": {
  "_ariaLabels": {
    "required": "Required",
    "optional": "Optional"
  }
}

These labels are translatable and can be customized for your course.

CSS Classes

The framework adds the following classes to elements with priority labels:

• is-priority-required - Added when the element is required
• is-priority-optional - Added when the element is optional

These classes allow you to style required and optional content differently (e.g., different colors, borders, or backgrounds).

Visual Examples

Priority labels displayed on Box Menu items

---

Priority label on a page header

---

Priority label on a block

---

Priority label on a component

Example Configurations

Show Optional Labels on Menu and Pages Only

This configuration displays "Optional" labels on menu items and pages, making it clear to learners which sections they can skip:

"_priorityLabels": {
  "_iconClassOptional": "icon-info",
  "_iconClassRequired": "",
  "_menuItem": {
    "_showWhenOptional": true,
    "_showWhenRequired": false
  },
  "_page": {
    "_showWhenOptional": true,
    "_showWhenRequired": false
  },
  "_article": {
    "_showWhenOptional": false,
    "_showWhenRequired": false
  },
  "_block": {
    "_showWhenOptional": false,
    "_showWhenRequired": false
  },
  "_component": {
    "_showWhenOptional": false,
    "_showWhenRequired": false
  }
}

Show Required Labels on All Content Types

This configuration emphasizes required content throughout the course:

"_priorityLabels": {
  "_iconClassOptional": "",
  "_iconClassRequired": "icon-exclamation",
  "_menuItem": {
    "_showWhenOptional": false,
    "_showWhenRequired": true
  },
  "_page": {
    "_showWhenOptional": false,
    "_showWhenRequired": true
  },
  "_article": {
    "_showWhenOptional": false,
    "_showWhenRequired": true
  },
  "_block": {
    "_showWhenOptional": false,
    "_showWhenRequired": true
  },
  "_component": {
    "_showWhenOptional": false,
    "_showWhenRequired": true
  }
}

Show Both Required and Optional Labels on Components

This configuration displays labels on components to highlight which activities must be completed:

"_priorityLabels": {
  "_iconClassOptional": "icon-info",
  "_iconClassRequired": "icon-exclamation",
  "_menuItem": {
    "_showWhenOptional": false,
    "_showWhenRequired": false
  },
  "_page": {
    "_showWhenOptional": false,
    "_showWhenRequired": false
  },
  "_article": {
    "_showWhenOptional": false,
    "_showWhenRequired": false
  },
  "_block": {
    "_showWhenOptional": false,
    "_showWhenRequired": false
  },
  "_component": {
    "_showWhenOptional": true,
    "_showWhenRequired": true
  }
}

Notes

• Priority labels respect the content hierarchy. If a parent element is optional, all its children are automatically optional, regardless of their individual settings.
• Labels only appear when a displayTitle is present. Hidden titles will not show priority labels.
• The default behavior (without any configuration) is to show no labels. You must explicitly enable them for each content type.
• When using the per-element override, you must set "_isOverride": true for the local settings to take effect.