SearchGuideLink appends and refines a search query. They appear under SearchField after user submits a search input.
Props
Usage guidelines
- To refine the original search query with more accurate and targeted keywords.
Best practices
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.
Truncate search queries to fit within a viewport.
Searchguides are serial and appear in multiples.
Searchguides should not be used as a single Searchguide.
Show high quality Searchguides that are relevant to the user’s search query.
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.
Do not show more than 9 Searchguides per search query.
Limiting vertical scrolling helps to enhance the user experience by reducing the effort required to navigate and locate content.
Do not use vertical scrolling for Searchguides.
Accessibility
ARIA attributes
When Searchguide text does not provide sufficient context about the Searchguide’s behavior, supply a short, descriptive label for screen-readers using accessibilityLabel.
If Searchguide is used as a control Searchguide to show/hide a Popover-based component, we recommend passing the following ARIA attributes to assist screen readers:
accessibilityLabel: if present, read by screen readers read instead of thetextprop.accessibilityControls: informs the screen reader that Searchguide controls the display of an anchored Popover-based component. It populates aria-controls.accessibilityHaspopup: informs the screen reader that there’s a Popover-based component attached to Searchguide. It populates aria-haspopup.accessibilityExpanded: informs the screen reader whether the searchguide-anchored Popover-based component is currently open or closed. It populates aria-expanded.
Also consider:
- 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.
Localization
Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.
Avoid truncating Searchguide text whenever possible. Refer to the Searchguide usage guidelines for more information
Variants
Colors
Use the color prop to change the background color of the Searchguide. The color prop can be one of the following values:
import { Box, Flex, SearchGuideLink, Text } from 'gestalt'; export default function Example() { return ( <Box padding={4}> <Flex gap={6} height="100%" width="100%" wrap> {['01', '02', '03', '04', '05', '06', '07', '08', '09', '10', '11'].map( (color) => { const colorCopy = color; return ( <Flex key={colorCopy} direction="column" gap={2}> <Box alignItems="center" borderStyle="sm" color="default" display="flex" height={200} justifyContent="center" rounding={4} width={200} > <SearchGuideLink color={colorCopy} href="https://pinterest.com" text={`Color ${color}`} /> </Box> <Text size="200" weight="bold"> color="{colorCopy}" </Text> </Flex> ); } )} </Flex> </Box> ); }
Thumbnail
Use the thumbnail prop to display an image to the left of the text. The thumbnail prop can be an
Avatar,
AvatarGroup,
Image, or
Icon.
import { Avatar, AvatarGroup, Flex, Icon, Image, SearchGuideLink, } from 'gestalt'; export default function Example() { return ( <Flex alignItems="center" direction="row" gap={2} height="100%" justifyContent="center" width="100%" > <SearchGuideLink accessibilityLabel="Fatima" color="02" href="https://pinterest.com" onClick={({ event, dangerouslyDisableOnNavigation }) => { event.preventDefault(); dangerouslyDisableOnNavigation(); }} text="Fatima" thumbnail={{ avatar: ( <Avatar name="Fatima" src="https://i.pinimg.com/originals/bf/bc/27/bfbc27685d81eb9a8f65c201ea661f0e.jpg" /> ), }} /> <SearchGuideLink accessibilityLabel="Ayesha and Sora" color="03" href="https://pinterest.com" onClick={({ event, dangerouslyDisableOnNavigation }) => { event.preventDefault(); dangerouslyDisableOnNavigation(); }} text="Ayesha and Sora" thumbnail={{ avatarGroup: ( <AvatarGroup accessibilityLabel="Pins: Ayesha, Sora." collaborators={[ { name: 'Ayesha', src: 'https://i.pinimg.com/originals/c5/5c/ac/c55caca43a7c16766215ec165b649c1c.jpg', }, { name: 'Sora', src: 'https://i.pinimg.com/originals/ab/c5/4a/abc54abd85df131e90ca6b372368b738.jpg', }, ]} size="md" /> ), }} /> <SearchGuideLink accessibilityLabel="Search" color="04" href="https://pinterest.com" onClick={({ event, dangerouslyDisableOnNavigation }) => { event.preventDefault(); dangerouslyDisableOnNavigation(); }} text="Search" thumbnail={{ icon: <Icon accessibilityLabel="search" icon="search" />, }} /> <SearchGuideLink accessibilityLabel="Design" color="01" href="https://pinterest.com" onClick={({ event, dangerouslyDisableOnNavigation }) => { event.preventDefault(); dangerouslyDisableOnNavigation(); }} text="Design" thumbnail={{ image: ( <Image alt="Design" naturalHeight={1} naturalWidth={1} src="https://i.ibb.co/3CT3Xnp/image.png" /> ), }} /> </Flex> ); }
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
Component quality checklist
Quality item | Status | Status description |
|---|---|---|
Figma Library | Partially ready | Component is live in Figma, however may not be available for all platforms. |
Responsive Web | Ready | Component responds to changing viewport sizes in web and mobile web. |
Internal documentation
Related
SearchGuide
Use SearchguideLink when a link is needed instead of an action.
SearchField
If the input is used for searching content, use SearchField.