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.

Examples

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.

Drag to resize example

Props

contextControl
React.ReactNode
Accepts a component that is used to help users switch between different contexts
onSearchResultsDismiss
onDismiss
A callback function that handles the dismissal of search results
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
searchResultsOverlayVisible
boolean
Whether or not the search results overlay has a visible backdrop
searchResultsVisible
boolean
A boolean property indicating whether search results are currently visible.
secondaryMenu
React.ReactNode
Accepts a menu component that is made available as a static member of the top bar component
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
onNavigationToggle
() => void
A callback function that handles hiding and showing mobile navigation

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

  • Search

  • search...

Top bar menu

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

Menu properties

Prop Type Description
activatorContent React.ReactNode Accepts an activator component that renders inside of a button that opens the menu
actions ActionListProps['sections'] An array of action objects that are rendered inside of a popover triggered by this menu
message MessageProps Accepts a message that facilitates direct, urgent communication with the merchant through the menu
open boolean A boolean property indicating whether the menu is currently open
onOpen() function A callback function to handle opening the menu popover
onClose() function A callback function to handle closing the menu popover

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

Menu properties

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

Top bar menu message

Message properties

Prop Type Description
title string A title for the message
description string A 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

Prop Type Description
value string Initial value for the input
placeholder string Hint text to display
focused boolean Force the focus state on the input
active boolean Force a state where search is active but the text field component is not focused
onChange(value: string) function Callback when value is changed
onFocus() function Callback when input is focused
onBlur() function Callback when focus is removed

Edit source on GitHub