Usage
Use a CFR (Contextual Feature Recommendation) to introduce a feature someone hasn't discovered yet, at a point where it's relevant to what they're doing. This is typically the first-time introduction of a new feature, either during onboarding or with a release, or the introduction of a significant change to something people already use. CFRs appear without being requested, so they should be used sparingly.
- Point the arrow at the element the message is about.
- Keep the header short and the description to a single sentence.
- Display one CFR at a time.
- Reassess a CFR after a few releases and retire it when it's no longer earning attention.
- Use a CFR for errors, confirmations, or anything a person is required to act on.
- Display a CFR alongside another message component.
- Display a CFR while the keyboard is open, unless the message is about the keyboard.
- Display more than two CFRs in a session, outside first-run onboarding.
- Repeat the same CFR to someone who has already seen it.
- Point at an element that's scrolled out of view or about to disappear.
Usage comparison
|
Component |
Interruption |
Blocking |
Placement |
Key difference from CFR |
|---|---|---|---|---|
|
CFR |
Medium |
No |
Anchored to an element |
– |
|
Toast |
Low |
No |
Floats above content, near the bottom of the screen |
Follows a user action, rather than appearing unprompted |
|
Alert |
High |
Yes |
Centered, overlays entire screen with scrim |
Interrupts and requires a response before continuing |
Design properties
| Property | Values | Default |
|---|---|---|
| Title Text | string | Header |
| Description Text | string | Description |
| Show Close Button Boolean | true | false | true |
| Type Variant | Default | Default |
| Show buttons Boolean | true | false | true |
Types
With actions
Header, description, close button, and two actions.
Without actions
A variant without actions.
Behavior and interaction
Triggers
A CFR is triggered by a specific event, and CFRs are prioritized against each other in code when more than one qualifies at the same time. Triggers include a feature becoming available for the first time, or a step within a sequence such as an onboarding tour.
Dismissal
A CFR doesn't dismiss on its own. It stays until someone closes it with the X or acts on an action.
Frequency
Show no more than two CFRs in a session, outside first-run onboarding, and never show the same CFR twice. We cap this because CFRs appear unrequested, and several in a row stops reading as helpful.
Positioning
Arrow direction
The arrow points at the element the message is about, so its direction depends on where that element sits on screen. Nine directions are available: none, leading, trailing, up leading, up center, up trailing, down leading, down center, and down trailing. Choose the one that connects the message to its element by the shortest path. Arrow direction is a setting rather than a type, so the examples above show one representative direction rather than all nine.
Related components
Changelog
|
Date |
Version |
Notes |
|---|---|---|
|
Sept 10, 2026 |
1.0.0 |
Initial draft of component guidance |