Prompt
Prompts are a way to choose one or multiple items from a large or unknown number of options.
Anatomy
Prompt are a form element that allow users to search for or browse through folders to select one or multiple options from a predetermined list, with options for progressive disclosure.
- Prompt Input: A form element that holds Pills. Tapping on the input opens a bottom sheet containing selectable options.
- Bottom Sheet: Full size modal bottom sheet containing the list of options as well as navigation options.
- Sheet Header: A modal sheet header is placed at the top of the Bottom Sheet, containing actions, the Prompt Label, and optionally a search input.
- Search Input (Optional): Holds the search query.
- Folders (Optional): List Item with a
wd-icon-chevron-rightsystem icon placed at the end to imply that this will take users deeper into the folder structure. - Expandable Containers (Optional): Show and hide options in a tree view to expand or collapse.
- Selection List: A list of single or multi-select List Items.
- Loading Dots (Conditional): Loading placeholder for list content. See Loading Dots for full details.
- Search Results Header: After search results have been found, a sticky header should indicate how many results have been returned from the search, if any.
Usage Guidance
- Prompts are most useful when you have a large list of predefined items that come from an external data source.
- Prompts have browse and search capabilities.
- Prompts are represented in a form by Prompt Input. Use
a
wd-system-icon-prompttrailing system icon, and not some other icon. - Selections display as a Pill in the Prompt Input.
- Selections may be added to or removed from the Prompt Input, but should not be edited or defined inline to the prompt.
Search
Search uses type-ahead to filter non-matching results and suggest selections while typing. It makes selecting from long lists of options more manageable by relying on recognition of a correct item rather than needing to recall exact terms.
Typehead
Type-ahead begins filtering results after 3 characters are typed to reduce the impact of performance. Instead of starting search after the first or second characters, 3 characters is applied as a constraint in the case of many items to compare against.
Do
Start the query after 3 characters are typed
Don't
Start searching premptively (before 3 characters)
Debounce
A debounce period of 300ms is used between searches to prevent search results appearing every time a new character is typed.
Loading
Use Loading Dots as placeholder for long load times to inform the user that content is actively loading into view. A visual placeholder to communicate loading can improve perceived performance by reducing the time to paint. If load times are insignificant consider not showing loading dots.
Use the table below when determining which loader to use:
| Loading Pattern | Time to Load | Indeterminate | Content is known |
|---|---|---|---|
| None | < 1s | All | n/a |
| 3 Dot Loader | 1s+ | All | n/a |
Search Results
By default, items are rendered as single or multi-select Radio or Checkbox List Items. If text matches the search term in an item, that text is bolded. A search results header containing the number of matching items is positioned at the top of the result list.
If no items are returned from the query, an empty state is used to inform the user that the search was not successful.
Browse
Page Title
By default the page title on the selection list screen is the same as the label of the input. However this title may be overridden to provide better context based on your use case.
List Items
Prompts can surface a hierarchy for users to navigate through.
Folders are built out of small List Items with a
wd-system-icon-chevron-small icon placed at the end.
Tapping on a folder will take the user to a smaller subset of options.
List Items in a folder should be of the same type, with each level of nesting increasing in specificity.
Don't
Mix and match types of content in folders.
Expand/Collapse
Expandable Containers show and hide related items without navigating somewhere else. These consist or either selection list items or folders - but not a mix of both.
Don't
Mix and match types of content in the container.
When to Use
- When options are dynamic, constantly changing and tied to an external dataset.
- When the number option is large and could benefit from pagination by folders
When to Use Something Else
- Use an inline Checkbox or Radio to show options in context to other form elements
- Use a Select dropdown when the number of options is less than 7 and is known.
- Use a Switch when options are a binary yes or no.
Examples
Not Required
If a Prompt is not required, all selections made are removable through the Tap Target on the Prompt.
Required
Required prompts are indicated by a red asterisk placed to the right of the Label. The last Pill in a Prompt Input will not be removable. Instead, the user should tap into the Prompt to make another selection or save the task for later.
Search
Not Searchable
Prompts are not searchable by default.
Searchable
Prompts can be made searchable through the native Search Input.
Selection
Single Select
Single select prompts are represented by a List Item with a leading Radio Buttons.
Multi Select
Use a ListItem with Checkbox to represent multi-select.
Hierarchical
Instances can be organized into hierarchical lists through Expandable Containers or List Items.
Expandable Container
Folders
API Guidelines
Methods
Class name: LabelledPromptWithLogging Module name: UIComponentsPlugin
public init(
featureData: FeatureMetricsData,
label: String,
isLoading: Binding<Bool> = .constant(false),
accessibilityLabel: String,
helperText: String?,
context: Binding<SemanticContext>,
searchHelper: Searchability.SearchHelper? = nil,
isEditable: Bool,
shouldBoldSearchResults: Bool = false,
content: [ListItem],
selections: Binding<Set<SelectableListItem>>,
isMultiSelect: Bool,
localizer: LocalizationAdapting,
contextMap: Binding<[String: SemanticContext]>,
promptId: String = UUID().uuidString
)Parameters
| Name | Description | Default values |
|---|---|---|
| featureData | the feature name/context and the screen ID in which the component appears. | |
| label | title of prompt input. | |
| isLoading | whether the prompt is showing a loading state instead of results. | .constant(false) |
| isLoadingSubSection | Whether prompt’s expandable section or folder page is showing loading instead of results. | .constant(false) |
| accessibilityLabel | the accessibility label for the prompt. | |
| helperText | the helper text for the prompt. | |
| context | the SemanticContext. | SemanticContext.default |
| searchHelper | optional Searchability.SearchHelper; if non-nil and the InstanceSet.DisplayIntention is a searchable list, then a search field will be provided bound to the options of this passed-in helper. | nil |
| isEditable | whether the prompt is editable (interactable). | |
| shouldBoldSearchResults | whether or not matching search results will be bolded based on the input search text. | false |
| content | binding to the ListItem array for this prompt. See usage guidelines below for UX suggestions. | nil |
| selections | binding to selected items. | nil |
| isMultiSelect | whether we support multiple selection or single select and dismiss. | |
| localizer | provider of localized strings, conforming to LocalizationAdapting. | |
| contextMap | each row in the list is bound to a SemanticContext in this dictionary by its ID (which is a String). This allows gesture recognizers on the rows to update whether they are inactive (deselected) or pressed, etc., and to maintain single selection logic. | |
| promptID | optional parameter to specify which prompt this is on the page. | UUID().uuidString |
Accessibility Guidelines
Coming soon!
Content Guidelines
Coming soon!
Anatomy
Prompt are a form element that allow users to search for or browse through folders to select one or multiple options from a predetermined list, with options for progressive disclosure.
- Prompt Input: A form element that holds Pills. Tapping on the input opens a bottom sheet containing selectable options.
- Bottom Sheet: Full size modal bottom sheet containing the list of options as well as navigation options.
- Sheet Header: A modal sheet header is placed at the top of the Bottom Sheet, containing actions, the Prompt Label, and optionally a search input.
- Search Input (Optional): Holds the search query.
- Folders (Optional): List Item with a
wd-icon-chevron-rightsystem icon placed at the end to imply that this will take users deeper into the folder structure. - Expandable Containers (Optional): Show and hide options in a tree view to expand or collapse.
- Selection List: A list of single or multi-select List Items.
- Loading Dots (Conditional): Loading placeholder for list content. See Loading Dots for full details.
- Search Results Header: After search results have been found, a sticky header should indicate how many results have been returned from the search, if any.
Usage Guidance
- Prompts are most useful when you have a large list of predefined items that come from an external data source.
- Prompts have browse and search capabilities.
- Prompts are represented in a form by Prompt Input.
Use a
wd-system-icon-prompttrailing system icon, and not some other icon. - Selections display as a Pill in the Prompt Input.
- Selections may be added to or removed from the Prompt Input, but should not be edited or defined inline to the prompt.
Search
Search uses type-ahead to filter non-matching results and suggest selections while typing. It makes selecting from long lists of options more manageable by relying on recognition of a correct item rather than needing to recall exact terms.
Typehead
Type-ahead begins filtering results after 3 characters are typed to reduce the impact of performance. Instead of starting search after the first or second characters, 3 characters is applied as a constraint in the case of many items to compare against.
Do
Start the query after 3 characters are typed
Don't
Start searching premptively (before 3 characters)
Debounce
A debounce period of 300ms is used between searches to prevent search results appearing every time a new character is typed.
Loading
Use Loading Dots as placeholder for long load times to inform the user that content is actively loading into view. A visual placeholder to communicate loading can improve perceived performance by reducing the time to paint. If load times are insignificant consider not showing loading dots.
Use the table below when determining which loader to use:
| Loading Pattern | Time to Load | Indeterminate | Content is known |
|---|---|---|---|
| None | < 1s | All | n/a |
| 3 Dot Loader | 1s+ | All | n/a |
Search Results
By default, items are rendered as single or multi-select Radio or Checkbox List Items. If text matches the search term in an item, that text is bolded. A search results header containing the number of matching items is positioned at the top of the result list.
If no items are returned from the query, an empty state is used to inform the user that the search was not successful.
Browse
Page Title
By default the page title on the selection list screen is the same as the label of the input. However this title may be overridden to provide better context based on your use case.
List Items
Prompts can surface a hierarchy for users to navigate through.
Folders are built out of small List Items with a
wd-system-icon-chevron-small icon placed at the end.
Tapping on a folder will take the user to a smaller subset of options.
List Items in a folder should be of the same type, with each level of nesting increasing in specificity.
Don't
Mix and match types of content in folders.
Expand/Collapse
Expandable Containers show and hide related items without navigating somewhere else. These consist or either selection list items or folders - but not a mix of both.
Don't
Mix and match types of content in the container.
When to Use
- When options are dynamic, constantly changing and tied to an external dataset.
- When the number option is large and could benefit from pagination by folders
When to Use Something Else
- Use an inline Checkbox or Radio to show options in context to other form elements
- Use a Select dropdown when the number of options is less than 7 and is known.
- Use a Switch when options are a binary yes or no.
Examples
Not required
If a Prompt is not required, all selections made are removable through the Tap Target on the Prompt.
Required
Required prompts are indicated by a red asterisk placed to the right of the Label. The last Pill in a Prompt Input will not be removable. Instead, the user should tap into the Prompt to make another selection or save the task for later.
Search
Not Searchable
Prompts are not searchable by default.
Searchable
Prompts can be made searchable through the native Search Input.
Selection
Single Select
Single select prompts are represented by a List Item with a leading Radio Buttons.
Multi Select
Use a ListItem with Checkbox to represent multi-select.
Hierarchical
Instances can be organized into hierarchical lists through Expandable Containers or List Items.
Expandable Container
Folders
API Guidelines
Methods
fun PromptUiComponent(
modifier: Modifier = Modifier,
searchListViewModel: SearchListViewModel,
label: String,
initialSelection: String? = null,
helperText: String? = null,
hasDivider: Boolean = false,
selectionListLoading: Boolean = false,
semanticState: SemanticState = SemanticState(),
searchEnabled: Boolean = true,
onPromptDismissed: @DisallowComposableCalls () -> Unit = {},
onClick: () -> Unit = {},
fetchFolderItems: ((ListItemUiModel) -> Unit)? = null,
onSearchTextChanged: ((String) -> Unit)? = null,
openDefaultModalOnClick: Boolean = true,
onItemSelected: (ListItemUiModel) -> Unit = {},
onPillRemoved: (ListItemUiModel) -> Unit = {},
)Parameters
| Name | Description | Default values |
|---|---|---|
| searchListViewModel | View model containing the UI State of prompt | |
| label | The text above the input that typically designates the name of the component | |
| initialSelection | Optional string that will create a pill in the prompt with an initial selection | null |
| helperText | Helper text is displayed underneath the input area to give additional context to the user. Error and Alert helper text prefixes are localized and automatically displayed when the component’s [semanticState] is changed | null |
| hasDivider | Boolean that controls whether to show the divider variant of the selection list | false |
| selectionListLoading | Boolean that puts the selection list into a loading state using the loading dots ui component when true. | false |
| semanticState | Adjusts the state of the Component. This allows for enabling, disabling, warning, error, and required states | SemanticState() |
| searchEnabled | Boolean that controls whether to show the search bar which makes the list filterable | true |
| onPromptDismissed | Callback lambda executed when the fullscreen or bottom sheet prompt has been dismissed | |
| onClick | Callback lambda executed when the prompt input is clicked | |
| fetchFolderItems | Callback lambda executed when folder sub items are fetched dynamically | null |
| onSearchTextChanged: | Callback lambda executed whenever the text of the search bar changes | null |
| openDefaultModalOnClick: | Boolean that controls whether to open the default modal when the prompt input is clicked | true |
| onItemSelected | Callback lambda executed when an item is selected | |
| onPillRemoved | Callback lambda executed when a pill is removed |
Content Guidelines
Coming soon!
Accessibility Guidelines
Coming soon!
Can't Find What You Need?
Check out our FAQ section which may help you find the information you're looking for. For further information, contact the #ask-canvas-design or #ask-canvas-kitchannels on Slack.