SearchGuide

SearchGuide appends and refines a search query. They appear under SearchField after user submits a search input.

also known as Search filters, Pivots, Vanilla guides

An example of a default search guide stream.

Usage guidelines

When to use
  • To refine the original search query with more accurate and targeted keywords
When not to use
  • To recommend related content or descriptions. Use Tag instead
  • To switch between different, yet related views. Use Tabs instead
  • To start a new search based solely on the content of the SearchGuide

Best practices

  • SearchGuides are serial and appear in multiples. When a query doesn’t produce enough guides of sufficient quality, they shouldn’t be shown
  • Limit the number of SearchGuides to 9 per search query. If there are fewer SearchGuides present for a given query, then by default we show that number. Limiting vertical scrolling helps to enhance the user experience by reducing the effort required to navigate and locate content
example of Search Guides placed correctly.
Do

Place SearchGuides at the start of the screen, and scroll horizontally to reveal additional guides. Note: be aware that off-screen guides have significantly lower engagement.

example of Search Guides being truncated.
Don't

Truncate search queries to fit within a viewport.

Accessibility

  • Ensure that each SearchGuide uses the correct markup for lists. Typically screen readers announce the number of items in a list and announce each item.
  • Limit the number of SearchGuides to 9 per search query. Horizontal scrolling can be challenging to users with mobility issues, or users of assistive devices such as screen readers.
  • Include descriptive alt text for icons and labels that convey the purpose of each item.
  • SearchGuide uses color tokens dynamically generated from the 300-value and below from the extended color palette. These values ensure SearchGuide has minimum contrast requirements met.

People use Apple’s accessibility features, such as reduced transparency, VoiceOver, and increased text size, to personalize how they interact with their device. Supporting these personalizations ensures that everyone has a great user experience. See Apple’s Human Interface Guidelines and API documentation about accessibility for iOS:

Design tokens

Anatomy

Default: 1. Container | 2. Text | 3. Trailing icon

Guide with image: 1. Pin image | 2. Text

Variants

Default

The default SearchGuide item displays a label only.

With an image

When SearchGuide query is more precise, a Pin representation can be added to illustrate the results.

Expandable

When a SearchGuide query is broad and can be further refined (example: Season), an arrow-down icon can be added at the end, to trigger a Sheet with a cluster of wrapped SearchGuides.

With Avatar

SearchGuide can display an Avatar when a brand filter is selected.

With AvatarGroup

SearchGuide can display an AvatarGroup when a filter for multiple brands is selected.

Leading icon

SearchGuide can display an optional leading icon.

Writing

  • Use short, meaningful labels that succinctly describe the search queries
  • Use the variants available as a guide to determine how specific the search query append should be
Edit page on GitHub