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

    Down Arrow

    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.