<!--
{
  "documentType" : "article",
  "framework" : "Swift Playgrounds",
  "identifier" : "/documentation/Swift-Playgrounds/giving-hints-to-help-learners-solve-problems",
  "metadataVersion" : "0.1.0",
  "role" : "article",
  "title" : "Giving hints to help learners solve problems"
}
-->

# Giving hints to help learners solve problems

Add hints, spoilers, and solutions to a page to help teach the material.

## Overview

Learners sometimes become stuck when working through a challenge or learning assessment.
Try to anticipate where learners are likely to become stuck when going through your
playground book, and provide hints to help them.

Hints are disclosed after the learner taps the Hint button in a page’s live view.

![A screenshot highlighting the Hint button in the bottom-right corner of a playground page’s live view.](images/com.apple.Swift-Playgrounds/giving-hints-to-help-learners-solve-problems-1@2x.png)

### Add hints by using a property list

Add hints to your playground page by creating a property list at the following path,
alongside the rest of the resources for the page:

*<book name>*`.playgroundbook/Contents/`*<chapter name>*`.playgroundchapter/Pages/`*<page
name>*`.playgroundpage/PrivateResources/Hints.plist`

The root key for the hints property list is named `Hints`, and it must contain an
array of dictionaries. Hints are shown in Swift Playgrounds in the same order as
they appear in this array.

### Add keys to the dictionaries

Add the following keys in each dictionary in the hints array:

- `Content`: The text of the hint.
- `FileReference`: The path to a text file that contains the hint. This path
  is relative to the page’s Resources folder, so a hint file located at the following
  path only needs to be referenced as `MyHint.txt` in the value of the `FileReference`
  key:
  
  *<book name>*`.playgroundbook/Contents/`*<chapter name>*`.playgroundchapter/Pages/`*<page
name>*`.playgroundpage/PrivateResources/MyHint.txt`
- `SpoilerButtonTitle`: A hint that’s hidden until the learner taps a button. Include
  the `SpoilerButtonTitle` key to hide the hint. The string you supply as the value
  for the key becomes the button’s title.

Don’t include both the `Content` and `FileReference` keys in the same dictionary.
You can use either one, but not both, because they both serve the role of provider
of the hint text.

You can use markup to format hint text. For more information, see 
[Markup Formatting
Reference](https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/index.html#//apple_ref/doc/uid/TP40016497).

### Create hints for various contexts

Create hints, spoilers, and solutions to suit the needs of each of your playground
pages. The example below shows each of the forms a hint can take.

```javascript
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Hints</key>
    <array>
        <dict>
            <key>Content</key>
            <string>Look at the `characters` property of `String`.</string>
        </dict>
        <dict>
            <key>Content</key>
            <string>This hint is initially hidden by a spoiler button.</string>
            <key>SpoilerButtonTitle</key>
            <string>Show Spoiler</string>
        </dict>
        <dict>
            <key>FileReference</key>
            <string>OutOfBandHint.txt</string>
        </dict>
        <dict>
            <key>FileReference</key>
            <string>OutOfBandHintWithSpoilerButton.txt</string>
            <key>SpoilerButtonTitle</key>
            <string>Show Spoiler</string>
        </dict>
    </array>
</dict>
</plist>
```

Here’s how the hints property list looks when displayed as a popover in the playground page’s
live view:

![A screenshot showing three hints. The top hint uses the “Content” key, the middle hint uses a spoiler sheet to hide the hint initially, and the bottom hint uses text from a file.](images/com.apple.Swift-Playgrounds/giving-hints-to-help-learners-solve-problems-2@2x.png)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)