# App home The [app home](https://shopify.dev/docs/apps/admin/embedded-app-home) is the primary surface for merchants to interact with your app, providing access to data and UI rendering within the Shopify Admin. Using Polaris components and App Bridge, you can integrate using the Web Platform APIs you're already familiar with, making it easy to build and maintain performant apps on the Shopify platform. ## Getting started To build for the App Home we recommend adding App Bridge and the Polaris Web Components to your application. Polaris web components provide a consistent UI experience that matches the Shopify Admin while leveraging standard web platform features. To use these components in your app, you need to include the experimental UI script in your application. Apps that use these components can also include pre-built UI [patterns](https://shopify.dev/docs/api/app-bridge-library/patterns) that are implemented using Polaris web components. These patterns help you quickly build consistent, familiar experiences for merchants that follow Shopify's design guidelines. ### New Remix Application Start building your app fast with the Shopify CLI and the [Shopify Remix App template](https://github.com/Shopify/shopify-app-template-remix). The CLI will set up App Bridge and the Polaris Web Components for you. As it is still a beta release you will need to select: 1. Select Build a Remix app (recommended) 2. Select JavaScript OR TypeScript (Polaris Early Access). ```shell POLARIS_UNIFIED=true shopify app init ``` ### Existing Remix Application Add the Polaris Web Components script tag to your `app/root.tsx` file's ``. To use the Remix router you will need to control the custom event `shopify:navigate` and push that into `useNavigate`. ```jsx import {useNavigate} from '@remix-run/react'; export default function App() { const navigate = useNavigate(); useEffect(() => { const handleNavigate = (event) => { const href = event.target.getAttribute('href'); if (href) navigate(href); }; document.addEventListener('shopify:navigate', handleNavigate); return () => { document.removeEventListener('shopify:navigate', handleNavigate); }; }, [navigate]); return ( ... ... ); } ``` ### Build your own way When building your own way add the script tag right after the existing App Bridge script tag in your HTML head. ```html ``` ## Your first API call The following example uses [`Resource Picker`](https://shopify.dev/docs/api/app-bridge-library/apis/resource-picker) to open a UI component that enables users to browse, find, and select products from their store using a familiar experiences. ```html ``` ## TypeScript Shopify App Bridge provides a companion npm library for TypeScript types, available at [`@shopify/app-bridge-types`](https://www.npmjs.com/package/@shopify/app-bridge-types). If you're using the [React library](https://shopify.dev/docs/api/app-bridge-library#react), then the types package is already included. Additionally, Shopify provides a companion npm library for Polaris web components types, available at [`@shopify/app-bridge-ui-types`](https://www.npmjs.com/package/@shopify/app-bridge-ui-types). ### App Bridge Installation The `@shopify/app-bridge-types` package can be installed using `yarn` or `npm`. ```shell npm install --save-dev @shopify/app-bridge-types ``` ```shell yarn add --dev @shopify/app-bridge-types ``` ### App Bridge Configuration Adding the `@shopify/app-bridge-types` package to your `tsconfig.json` file will enable type checking for all files in your project. ```json { "compilerOptions": { "types": ["@shopify/app-bridge-types"] } } ``` ### Polaris Web Components Installation The `@shopify/app-bridge-ui-types` package can be installed using `yarn` or `npm`. Specify `latest` in package.json if using https://cdn.shopify.com/shopifycloud/app-bridge-ui-experimental.js. ```shell npm install --save-dev @shopify/app-bridge-ui-types ``` ```shell yarn add --dev @shopify/app-bridge-ui-types ``` ```json { "devDependencies": { "@shopify/app-bridge-ui-types": "latest" } } ``` ### Polaris Web Components Configuration Adding the `@shopify/app-bridge-ui-types` package to your `tsconfig.json` file will enable type checking for all files in your project. ```json { "compilerOptions": { "types": ["@shopify/app-bridge-ui-types"] } } ``` ## Global variable After App Bridge is set up in your app, you have access to the `shopify` global variable. This variable exposes various App Bridge functionalities, such as [displaying toast notifications](https://shopify.dev/docs/api/app-bridge-library/apis/toast) or [retrieving app configuration details](https://shopify.dev/docs/api/app-bridge-library/apis/config). To explore all the functionality available on the `shopify` global variable: 1. Open the Chrome developer console while in the Shopify admin. 2. Switch the frame context to your app's `iframe`. 3. Enter `shopify` in the console. ## Direct API access You can make requests to the Admin API directly from your app using the standard [web `fetch` API](https://developer.mozilla.org/en-US/docs/Web/API/fetch)! Any `fetch()` calls from your app to Shopify's Admin GraphQL API are automatically authenticated by default. These calls are fast too, because Shopify handles requests directly. Direct API access is disabled by default. It can be [enabled](https://shopify.dev/docs/apps/tools/cli/configuration#admin) in your app TOML file, along with whether you want to use direct API access with [online access](https://shopify.dev/docs/apps/auth/oauth/access-modes#online-access) or [offline access](https://shopify.dev/docs/apps/auth/oauth/access-modes#offline-access) mode. ```js const res = await fetch('shopify:admin/api/2025-04/graphql.json', { method: 'POST', body: JSON.stringify({ query: ` query GetProduct($id: ID!) { product(id: $id) { title } } `, variables: {id: 'gid://shopify/Product/1234567890'}, }), }); const {data} = await res.json(); console.log(data); ``` - [Learn more about API access modes](https://shopify.dev/docs/apps/tools/cli/configuration): Configuration guide ## Migration If you have an app that uses components and hooks from Shopify App Bridge React 3.x.x, then you can follow the [migration guide](https://shopify.dev/docs/api/app-bridge/migration-guide) to upgrade your components and hooks to the latest version. ## Next steps Now that you've initialized your app, you can use any [Shopify App Bridge features](https://shopify.dev/docs/api/app-bridge-library/apis). ## References - [ui-modal](https://shopify.dev/docs/api/app-home/app-bridge-web-components/ui-modal.txt): Displays an overlay with important information. - [ui-nav-menu](https://shopify.dev/docs/api/app-home/app-bridge-web-components/ui-nav-menu.txt): Creates a navigation menu for your app. - [ui-save-bar](https://shopify.dev/docs/api/app-home/app-bridge-web-components/ui-save-bar.txt): Display a save bar from your app. - [ui-title-bar](https://shopify.dev/docs/api/app-home/app-bridge-web-components/ui-title-bar.txt): Populates the title bar for your app. - [Config](https://shopify.dev/docs/api/app-home/apis/config.txt): Configuration information for your app - [Environment](https://shopify.dev/docs/api/app-home/apis/environment.txt): Platform information for App Home - [Resource Fetching](https://shopify.dev/docs/api/app-home/apis/resource-fetching.txt): Send an authenticated fetch request - [ID Token](https://shopify.dev/docs/api/app-home/apis/id-token.txt): Retrieves an ID token from Shopify - [Loading](https://shopify.dev/docs/api/app-home/apis/loading.txt): Displays a loading indicator - [Modal](https://shopify.dev/docs/api/app-home/apis/modal.txt): Displays an overlay with important information. - [Navigation](https://shopify.dev/docs/api/app-home/apis/navigation.txt): Allows you to navigate within and outside of your app - [Picker](https://shopify.dev/docs/api/app-home/apis/picker.txt): Opens a Picker in your app - [POS](https://shopify.dev/docs/api/app-home/apis/pos.txt): Interact and retrieve data for the POS - [Print](https://shopify.dev/docs/api/app-home/apis/print.txt): Print the App Home page from a mobile device - [useAppBridge](https://shopify.dev/docs/api/app-home/react-hooks/useappbridge.txt): Enables you to access the `shopify` global in your app. - [Resource Picker](https://shopify.dev/docs/api/app-home/apis/resource-picker.txt): Opens a Resource Picker in your app - [Reviews](https://shopify.dev/docs/api/app-home/apis/reviews.txt): Request an app review modal in the Shopify admin - [Save Bar](https://shopify.dev/docs/api/app-home/apis/save-bar.txt): Display a save bar when a form has unsaved changes. - [Scanner](https://shopify.dev/docs/api/app-home/apis/scanner.txt): Use the mobile device's camera to scan barcodes - [Scopes](https://shopify.dev/docs/api/app-home/apis/scopes.txt): Manage optional access scopes - [Share](https://shopify.dev/docs/api/app-home/apis/share.txt): Share content from your App Home on a mobile device - [Support](https://shopify.dev/docs/api/app-home/apis/support.txt): Register a custom handler for support requests. - [Toast](https://shopify.dev/docs/api/app-home/apis/toast.txt): Creates a Toast notification in your app - [User](https://shopify.dev/docs/api/app-home/apis/user.txt): Retrieves information about the current user - [Web Vitals](https://shopify.dev/docs/api/app-home/apis/web-vitals.txt): Monitor Web Vitals for your app - [Details](https://shopify.dev/docs/api/app-home/patterns/details.txt): Edit and view objects with efficient dual-column layout. - [Homepage](https://shopify.dev/docs/api/app-home/patterns/homepage.txt): Design your app homepage for daily merchant value. - [Index](https://shopify.dev/docs/api/app-home/patterns/index.txt): Manage objects efficiently with dynamic table actions. - [Settings](https://shopify.dev/docs/api/app-home/patterns/settings.txt): Organize settings into categories for easy navigation. - [Avatar](https://shopify.dev/docs/api/app-home/polaris-web-components/media/avatar.txt): Show a user’s profile image or initials in a compact, visual element. - [Badge](https://shopify.dev/docs/api/app-home/polaris-web-components/titles-and-text/badge.txt): Inform users about the status of an object or indicate that an action has been completed. - [Banner](https://shopify.dev/docs/api/app-home/polaris-web-components/feedback/banner.txt): Highlights important information or required actions prominently within the interface. Use to communicate statuses, provide feedback, or draw attention to critical updates. - [Box](https://shopify.dev/docs/api/app-home/polaris-web-components/structure/box.txt): A generic container that provides a flexible alternative for custom designs not achievable with existing components. Use it to apply styling such as backgrounds, padding, or borders, or to nest and group other components. The contents of Box always maintain their natural size, making it especially useful within layout components that would otherwise stretch their children. - [Button](https://shopify.dev/docs/api/app-home/polaris-web-components/actions/button.txt): Triggers actions or events, such as submitting forms, opening dialogs, or navigating to other pages. Use Button to let users perform specific tasks or initiate interactions throughout the interface. Buttons can also function as links, guiding users to internal or external destinations. - [Checkbox](https://shopify.dev/docs/api/app-home/polaris-web-components/forms/checkbox.txt): Give users a clear way to make selections, such as agreeing to terms or choosing multiple items from a list. - [ChoiceList](https://shopify.dev/docs/api/app-home/polaris-web-components/forms/choicelist.txt): Present multiple options to users, allowing either single selections with radio buttons or multiple selections with checkboxes. - [Clickable](https://shopify.dev/docs/api/app-home/polaris-web-components/actions/clickable.txt): A generic interactive container component that provides a flexible alternative for custom interactive elements not achievable with existing components like Button or Link. Use it to apply specific styling such as backgrounds, padding, or borders. - [DatePicker](https://shopify.dev/docs/api/app-home/polaris-web-components/forms/datepicker.txt): Allow users to select a specific date or date range. - [Divider](https://shopify.dev/docs/api/app-home/polaris-web-components/structure/divider.txt): Create clear visual separation between elements in your user interface. - [EmailField](https://shopify.dev/docs/api/app-home/polaris-web-components/forms/emailfield.txt): Let users enter email addresses with built-in validation and optimized keyboard settings. - [Grid](https://shopify.dev/docs/api/app-home/polaris-web-components/structure/grid.txt): Use `s-grid` to organize your content in a matrix of rows and columns and make responsive layouts for pages. Grid follows the same pattern as the [CSS grid layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout). - [Heading](https://shopify.dev/docs/api/app-home/polaris-web-components/titles-and-text/heading.txt): Renders hierarchical titles to communicate the structure and organization of page content. Heading levels adjust automatically based on nesting within parent Section components, ensuring a meaningful and accessible page outline. - [Icon](https://shopify.dev/docs/api/app-home/polaris-web-components/media/icon.txt): Renders a graphic symbol to visually communicate core parts of the product and available actions. Icons can act as wayfinding tools to help users quickly understand their location within the interface and common interaction patterns. - [Image](https://shopify.dev/docs/api/app-home/polaris-web-components/media/image.txt): Embeds an image within the interface and controls its presentation. Use to visually illustrate concepts, showcase products, or support user tasks and interactions. - [Link](https://shopify.dev/docs/api/app-home/polaris-web-components/actions/link.txt): Makes text interactive, allowing users to navigate to other pages or perform specific actions. Supports standard URLs, custom protocols, and navigation within Shopify or app pages. - [MoneyField](https://shopify.dev/docs/api/app-home/polaris-web-components/forms/moneyfield.txt): Collect monetary values from users with built-in currency formatting and validation. - [NumberField](https://shopify.dev/docs/api/app-home/polaris-web-components/forms/numberfield.txt): Collect numerical values from users with optimized keyboard settings and built-in validation. - [OrderedList](https://shopify.dev/docs/api/app-home/polaris-web-components/structure/orderedlist.txt): Displays a numbered list of related items in a specific sequence. Use to present step-by-step instructions, ranked items, or procedures where order matters. - [Page](https://shopify.dev/docs/api/app-home/polaris-web-components/structure/page.txt): Use `s-page` as the main container for placing content in your app. Page comes with preset layouts and automatically adds spacing between elements. - [Paragraph](https://shopify.dev/docs/api/app-home/polaris-web-components/titles-and-text/paragraph.txt): Displays a block of text, and can contain inline elements such as buttons, links, or emphasized text. Use to present standalone blocks of content, as opposed to inline text. - [PasswordField](https://shopify.dev/docs/api/app-home/polaris-web-components/forms/passwordfield.txt): Securely collect sensitive information from users. - [QueryContainer](https://shopify.dev/docs/api/app-home/polaris-web-components/structure/querycontainer.txt): Establishes a query container for responsive design. Use `s-query-container` to define an element as a containment context, enabling child components or styles to adapt based on the container’s size. - [SearchField](https://shopify.dev/docs/api/app-home/polaris-web-components/forms/searchfield.txt): Let users enter search terms or find specific items using a single-line input field. - [Section](https://shopify.dev/docs/api/app-home/polaris-web-components/structure/section.txt): Groups related content into clearly-defined thematic areas. Sections have contextual styling that automatically adapts based on nesting depth. They also adjust heading levels to maintain a meaningful and accessible page structure. - [Select](https://shopify.dev/docs/api/app-home/polaris-web-components/forms/select.txt): Allow users to pick one option from a menu. Ideal when presenting four or more choices to keep interfaces uncluttered. - [Spinner](https://shopify.dev/docs/api/app-home/polaris-web-components/feedback/spinner.txt): Displays an animated indicator showing users that content or actions are loading. Use to communicate ongoing processes, such as fetching data from a server. For loading states on buttons, use the “loading” property on the Button component instead. - [Stack](https://shopify.dev/docs/api/app-home/polaris-web-components/structure/stack.txt): Organizes elements horizontally or vertically along the block or inline axis. Use to structure layouts, group related components, or control spacing between elements. - [Switch](https://shopify.dev/docs/api/app-home/polaris-web-components/forms/switch.txt): Give users a clear way to toggle options on or off. - [Table](https://shopify.dev/docs/api/app-home/polaris-web-components/structure/table.txt): Display data clearly in rows and columns, helping users view, analyze, and compare information. Automatically renders as a list on small screens and a table on large ones. - [Text](https://shopify.dev/docs/api/app-home/polaris-web-components/titles-and-text/text.txt): Displays inline text with specific visual styles or tones. Use to emphasize or differentiate words or phrases within a Paragraph or other block-level components. - [TextArea](https://shopify.dev/docs/api/app-home/polaris-web-components/forms/textarea.txt): Collect longer text content from users with a multi-line input that expands automatically. - [TextField](https://shopify.dev/docs/api/app-home/polaris-web-components/forms/textfield.txt): Lets users enter or edit text within a single-line input. Use to collect short, free-form information from users. - [Thumbnail](https://shopify.dev/docs/api/app-home/polaris-web-components/media/thumbnail.txt): Display a small preview image representing content, products, or media. - [URLField](https://shopify.dev/docs/api/app-home/polaris-web-components/forms/urlfield.txt): Collect URLs from users with built-in formatting and validation. - [UnorderedList](https://shopify.dev/docs/api/app-home/polaris-web-components/structure/unorderedlist.txt): Displays a bulleted list of related items. Use to present collections of items or options where the sequence isn’t critical.