SearchGuideLink

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

Figma:

Responsive:

Adaptive:

Props

Component props
Name	Type	Default
`href` Required	`string`	-
	Specifies a link URL.
`text` Required	`string`	-
	Text to render inside the SearchGuideLink to convey the function and purpose of the SearchGuideLink. It can be empty, but is still required as a fallback to accessibilityLabel.
`accessibilityLabel`	`string`	-
	Label for screen readers to announce SearchGuideLink. See the Accessibility guidelines for details on proper usage.
`color`	`"01" \| "02" \| "03" \| "04" \| "05" \| "06" \| "07" \| "08" \| "09" \| "10" \| "11"`	`1`
	The background color of SearchGuideLink. See the color variant for implementation guidance.
`dataTestId`	`string`	-
	Available for testing purposes, if needed. Consider better queries before using this prop.
`onClick`	`(arg1: { event: React.MouseEvent<HTMLAnchorElement> \| React.KeyboardEvent<HTMLAnchorElement>; dangerouslyDisableOnNavigation: () => void; }) => void`	-
	Callback invoked when the user clicks (press and release) on ButtonLink with the mouse or keyboard. See GlobalEventsHandlerProvider to learn more about link navigation.
`rel`	`"none" \| "nofollow"`	`"none"`
	Provides hints for SEO. See the MDN Web Docs to learn more.
`tabIndex`	`-1 \| 0`	`0`
	Use "-1" to remove ButtonLink from keyboard navigation. See the Accessibility guidelines to learn more.
`target`	`null \| "self" \| "blank"`	`"null"`
	Indicates the browsing context where an href will be opened: 'null' opens the anchor in the same window. 'blank' opens the anchor in a new window. 'self' opens an anchor in the same frame.
`thumbnail`	`{ avatar: ReactElement } \| { avatarGroup: ReactElement } \| { image: ReactElement } \| { icon: ReactElement }`	-
	The thumbnail prop is used to display an image or icon to the left of the text. See the thumbnail variant to learn more.

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

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.

Don't

Truncate search queries to fit within a viewport.

Searchguides are serial and appear in multiples.

Don't

Searchguides should not be used as a single Searchguide.

Show high quality Searchguides that are relevant to the user’s search query.

Don't

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.

Don't

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.

Don't

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 the text prop.
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) => (
            <Flex key={color} direction="column" gap={2}>
              <Box
                alignItems="center"
                borderStyle="sm"
                color="default"
                display="flex"
                height={200}
                justifyContent="center"
                rounding={4}
                width={200}
              >
                <SearchGuideLink
                  backgroundContext={
                    color === 'transparentWhiteText' ? 'dark' : 'light'
                  }
                  color={color}
                  href="https://pinterest.com"
                  text="Save"
                />
              </Box>
              <Text size="200" weight="bold">
                color=&quot;{color}&quot;
              </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="column"
      gap={4}
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <SearchGuideLink
        accessibilityLabel="Image"
        color="01"
        href="https://pinterest.com"
        text="Image"
        thumbnail={{
          image: (
            <Image
              alt="Image"
              naturalHeight={1}
              naturalWidth={1}
              src="https://i.ibb.co/bBXC23j/fashion.jpg"
            />
          ),
        }}
      />
      <SearchGuideLink
        accessibilityLabel="Icon"
        color="02"
        href="https://pinterest.com"
        text="Icon"
        thumbnail={{
          icon: <Icon accessibilityLabel="" icon="sparkle" />,
        }}
      />
      <SearchGuideLink
        accessibilityLabel="Avatar"
        color="03"
        href="https://pinterest.com"
        text="Avatar"
        thumbnail={{
          avatar: (
            <Avatar name="Keerthi" src="https://i.ibb.co/ZfCZrY8/keerthi.jpg" />
          ),
        }}
      />
      <SearchGuideLink
        accessibilityLabel="AvatarGroup"
        color="04"
        href="https://pinterest.com"
        text="AvatarGroup"
        thumbnail={{
          avatarGroup: (
            <AvatarGroup
              accessibilityLabel="Collaborators: Keerthi, Alberto, Enio."
              collaborators={[
                {
                  name: 'Keerthi',
                  src: 'https://i.ibb.co/ZfCZrY8/keerthi.jpg',
                },
                {
                  name: 'Alberto',
                  src: 'https://i.ibb.co/NsK2w5y/Alberto.jpg',
                },
                {
                  name: 'Enio',
                },
              ]}
              size="md"
            />
          ),
        }}
      />
    </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

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

PDocs available

SearchGuide
Use SearchguideLink when a link is needed instead of an action.

SearchField
If the input is used for searching content, use SearchField.

Edit page on GitHub

SearchGuideLink

Props

Usage guidelines

Best practices

Accessibility

ARIA attributes

Localization

Variants

Colors

Thumbnail

Writing

Component quality checklist

Internal documentation

Related