Top bar

The top bar is a header component that allows merchants to search, access menus, and navigate by clicking on the logo. It’s always visible at the top of interfaces like Shopify or Shopify Plus. Third-party apps that use the top bar can customize the color to match their brand using the app provider component and are required to use their own logo.

Use to provide structure for the top of an application. Style the top bar component using the app provider component with a theme. Providing just the background key for the top bar component theme will result in intelligent defaults being set for complementary colors with contrasting text.

import {
  TopBar,
  ActionList,
  Icon,
  VisuallyHidden,
  Frame,
} from '@shopify/polaris';
import {ArrowLeftMinor, QuestionMarkMajor} from '@shopify/polaris-icons';
import {useState, useCallback} from 'react';

function TopBarExample() {
  const [isUserMenuOpen, setIsUserMenuOpen] = useState(false);
  const [isSecondaryMenuOpen, setIsSecondaryMenuOpen] = useState(false);
  const [isSearchActive, setIsSearchActive] = useState(false);
  const [searchValue, setSearchValue] = useState('');

  const toggleIsUserMenuOpen = useCallback(
    () => setIsUserMenuOpen((isUserMenuOpen) => !isUserMenuOpen),
    [],
  );

  const toggleIsSecondaryMenuOpen = useCallback(
    () => setIsSecondaryMenuOpen((isSecondaryMenuOpen) => !isSecondaryMenuOpen),
    [],
  );

  const handleSearchResultsDismiss = useCallback(() => {
    setIsSearchActive(false);
    setSearchValue('');
  }, []);

  const handleSearchChange = useCallback((value) => {
    setSearchValue(value);
    setIsSearchActive(value.length > 0);
  }, []);

  const handleNavigationToggle = useCallback(() => {
    console.log('toggle navigation visibility');
  }, []);

  const logo = {
    width: 124,
    topBarSource:
      'https://cdn.shopify.com/s/files/1/0446/6937/files/jaded-pixel-logo-color.svg?6215648040070010999',
    url: 'http://jadedpixel.com',
    accessibilityLabel: 'Jaded Pixel',
  };

  const userMenuMarkup = (
    <TopBar.UserMenu
      actions={[
        {
          items: [{content: 'Back to Shopify', icon: ArrowLeftMinor}],
        },
        {
          items: [{content: 'Community forums'}],
        },
      ]}
      name="Dharma"
      detail="Jaded Pixel"
      initials="D"
      open={isUserMenuOpen}
      onToggle={toggleIsUserMenuOpen}
    />
  );

  const searchResultsMarkup = (
    <ActionList
      items={[{content: 'Shopify help center'}, {content: 'Community forums'}]}
    />
  );

  const searchFieldMarkup = (
    <TopBar.SearchField
      onChange={handleSearchChange}
      value={searchValue}
      placeholder="Search"
      showFocusBorder
    />
  );

  const secondaryMenuMarkup = (
    <TopBar.Menu
      activatorContent={
        <span>
          <Icon source={QuestionMarkMajor} />
          <VisuallyHidden>Secondary menu</VisuallyHidden>
        </span>
      }
      open={isSecondaryMenuOpen}
      onOpen={toggleIsSecondaryMenuOpen}
      onClose={toggleIsSecondaryMenuOpen}
      actions={[
        {
          items: [{content: 'Community forums'}],
        },
      ]}
    />
  );

  const topBarMarkup = (
    <TopBar
      showNavigationToggle
      userMenu={userMenuMarkup}
      secondaryMenu={secondaryMenuMarkup}
      searchResultsVisible={isSearchActive}
      searchField={searchFieldMarkup}
      searchResults={searchResultsMarkup}
      onSearchResultsDismiss={handleSearchResultsDismiss}
      onNavigationToggle={handleNavigationToggle}
    />
  );

  return (
    <div style={{height: '250px'}}>
      <Frame topBar={topBarMarkup} logo={logo} />
    </div>
  );
}

Props

Want to help make this feature better? Please share your feedback.

interface TopBarProps
showNavigationToggle?boolean

Toggles whether or not a navigation component has been provided. Controls the presence of the mobile nav toggle button.

userMenu?React.ReactNode

Accepts a user component that is made available as a static member of the top bar component and renders as the primary menu.

secondaryMenu?React.ReactNode

Accepts a menu component that is made available as a static member of the top bar component.

contextControl?React.ReactNode

Accepts a component that is used to help users switch between different contexts.

searchField?React.ReactNode

Accepts a search field component that is made available as a `TextField` static member of the top bar component.

searchResults?React.ReactNode

Accepts a search results component that is ideally composed of a card component containing a list of actionable search results.

searchResultsVisible?boolean

A boolean property indicating whether search results are currently visible.

searchResultsOverlayVisible?boolean

Whether or not the search results overlay has a visible backdrop.

onSearchResultsDismiss?() => void

A callback function that handles the dismissal of search results.

onNavigationToggle?() => void

A callback function that handles hiding and showing mobile navigation.

logoSuffix?React.ReactNode

Accepts a component that is used to supplement the logo markup.

Required components

The top bar component must be passed to the frame component.


Best practices

The top bar component should:

  • Not provide global navigation for an application
  • Include search to help merchants find resources and navigate an application
  • Include a user menu component to indicate the logged-in merchant and provide them with global actions
  • Provide a color through the app provider component to style the background
  • The global menu text should contrast with the rest of the top bar and pass the minimum contrast ratio of the WCAG 2.0 guidelines
  • Use an SVG file for the logo
  • Use a logo that passes the minimum contrast ratio of the WCAG 2.0 guidelines when compared to the top bar background color
  • Show the navigation toggle so it appears on small screen

Content guidelines

Placeholder content

The placeholder content for the search field should:

  • Always say "Search"
  • Never include an ellipsis

Do

  • Search

Don’t

  • search...

Top bar menu

A component that composes together an activator and a popover containing an action list to create a dropdown menu.

PropTypeDescription
activatorContentReact.ReactNodeAccepts an activator component that renders inside of a button that opens the menu
actionsActionListProps['sections']An array of action objects that are rendered inside of a popover triggered by this menu
messageMessagePropsAccepts a message that facilitates direct, urgent communication with the merchant through the menu
openbooleanA boolean property indicating whether the menu is currently open
onOpen()functionA callback function to handle opening the menu popover
onClose()functionA callback function to handle closing the menu popover

Top bar user menu

A specialized menu component that is activated by a user avatar.

PropTypeDescription
actions{items: IconableAction[]}[]An array of action objects that are rendered inside of a popover triggered by this menu
messageMessagePropsAccepts a message that facilitates direct, urgent communication with the merchant through the user menu
namestringA string detailing the merchant’s full name to be displayed in the user menu
detailstringA string allowing further details on the merchant’s name displayed in the user menu
initialsAvatarProps['initials']The merchant’s initials, rendered in place of an avatar image when not provided
avatarAvatarProps['source']An avatar image representing the merchant
openbooleanA boolean property indicating whether the user menu is currently open
onToggle()functionA callback function to handle opening and closing the user menu

Top bar menu message

Message properties

PropTypeDescription
titlestringA title for the message
descriptionstringA description for the message
action{onClick(): void; content: string}An action to render near the message
link{to: string; content: string}A link to view the content of the message
badge{content: string; status: BadgeProps['status']}A badge to render near the message

Top bar search field

A text field component that is tailor-made for a search use-case.

Search field properties

PropTypeDescription
valuestringInitial value for the input
placeholderstringHint text to display
focusedbooleanForce the focus state on the input
activebooleanForce a state where search is active but the text field component is not focused
onChange(value: string)functionCallback when value is changed
onFocus()functionCallback when input is focused
onBlur()functionCallback when focus is removed

  • To provide the structure for the top bar component, as well as the primary navigation use the frame component.
  • To display the primary navigation within the frame of an application, use the navigation component.
  • To tell merchants their options once they have made changes to a form on the page use the contextual save bar component.
  • To provide quick, at-a-glance feedback on the outcome of an action, use the toast component.
  • To indicate to merchants that a page is loading or an upload is processing use the loading component.