Shop Minis

https://shopify.dev/docs/api/shop-minis
Admin
Shop Minis is a React SDK that enables developers to build fast, immersive shopping experiences for...
Tokens:31,330
Snippets:318
Trust Score:10
Update:10 months ago
Show doc for...
Tokens:
Raw
### Get Shop Minis Version Info (CLI)

Source: https://shopify.dev/docs/api/shop-minis/commands/info

Execute the 'shop-minis info' command to display version details of your OS, Node.js, npm, and other relevant development tools. This command is useful for diagnosing compatibility issues or understanding your current environment setup. The --verbose flag provides additional debugging output.

```bash
npx shop-minis info [options]
```

--------------------------------

### Create Shop Mini Command (CLI)

Source: https://shopify.dev/docs/api/shop-minis/commands/create

Scaffolds a new Shop Mini project using the 'create' command. This command initializes a new Mini project from an example template, installs dependencies, and sets up the project structure. It requires the 'mini name' and optionally accepts '--output-dir' and '--verbose' flags.

```bash
npx shop-minis create [options] [mini name]
```

--------------------------------

### Set Up New Mini Project with Default Options

Source: https://shopify.dev/docs/api/shop-minis/commands/setup

Executes the default setup for a new Shopify Mini project. This command registers the Mini with Shopify Partners, links it to your organization, generates API keys, and saves them to your .env file. No external dependencies are required beyond the shop-minis CLI.

```shell
npx shop-minis setup [options]
```

--------------------------------

### Shop Mini Manifest Structure Example

Source: https://shopify.dev/docs/api/shop-minis/manifest-file

An example of a complete `manifest.json` file for a Shop Mini. This file defines the core configuration, including permissions, scopes, and trusted domains, which are validated during the submission process.

```json
{
  "name": "My Shop Mini",
  "version": "1.0.0",
  "description": "A sample Shop Mini.",
  "permissions": [
    "CAMERA",
    "MICROPHONE"
  ],
  "scopes": [
    "profile",
    "orders"
  ],
  "trusted_domains": [
    "example.com",
    "api.example.com/v1"
  ]
}
```

--------------------------------

### Install Dependency with Shopify CLI

Source: https://shopify.dev/docs/api/shop-minis/commands/install

Installs a specified dependency, allowing version pinning (e.g., react@^18.0.0). This is the primary command for adding new packages to your project.

```bash
npx shop-minis install [options] [dependency]
```

--------------------------------

### Shopify Shop Minis React Progress Component Examples

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/progress

Provides examples of the Progress component in different states: half progress (50% completion) and complete progress (100% completion). These examples showcase how to configure the 'value' prop to represent various stages of progress.

```javascript
import {Progress} from '@shopify/shop-minis-react'

export default function MyComponent() {
  return <Progress value={50} />
}
```

```javascript
import {Progress} from '@shopify/shop-minis-react'

export default function MyComponent() {
  return <Progress value={100} />
}
```

--------------------------------

### Install Lucide React Icon Library for Shop Minis

Source: https://shopify.dev/docs/api/shop-minis/design

This command installs the Lucide React icon library, which is recommended for use in Shop Minis due to its consistent design, customizability, and cross-platform rendering. Icons should be preferred over emojis for UI elements.

```bash
npx shop-minis install lucide-react
```

--------------------------------

### Check Dependencies with Shopify CLI

Source: https://shopify.dev/docs/api/shop-minis/commands/install

Checks if installed dependencies are valid and up-to-date. This command can be used with the `--fix` option to automatically resolve issues or with `--json` to output results in a machine-readable format.

```bash
npx shop-minis install --check [dependency]
npx shop-minis install --check --json [dependency]
npx shop-minis install --fix [dependency]
```

--------------------------------

### Basic TransitionLink Usage in React

Source: https://shopify.dev/docs/api/shop-minis/shop-minis/components/TransitionLink

Demonstrates the basic setup for using TransitionLink components within a MinisRouter. This example shows how to create navigation links for Home, Products, and Cart, ensuring that the MinisRouter is configured with the 'viewTransitions' prop enabled for animated page changes.

```javascript
import React from 'react'
import {MinisRouter, TransitionLink} from '@shopify/shop-minis-react'
import {Routes, Route} from 'react-router'

function Navigation() {
  return (
    <nav>
      <TransitionLink to="/">Home</TransitionLink>
      <TransitionLink to="/products">Products</TransitionLink>
      <TransitionLink to="/cart">Cart</TransitionLink>
    </nav>
  )
}

function App() {
  return (
    <div>
      <MinisRouter viewTransitions>
        <Routes>
          <Route path="/" element={<Navigation />} />
        </Routes>
      </MinisRouter>
    </div>
  )
}

export default App

```

--------------------------------

### React Input Component Examples - Shopify Shop Minis

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/input

Demonstrates the usage of the Input component from '@shopify/shop-minis-react'. It shows how to set placeholders, initial values, and handle input changes. This component is built using React.

```jsx
import {Input} from '@shopify/shop-minis-react'
  
export default function MyComponent() {
return (
<Input
placeholder="Enter text..."
value="This is an input"
onChange={e => console.log(e.target.value)}
/>
)
}
```

```jsx
import {Input} from '@shopify/shop-minis-react'

export default function MyComponent() {
  return (
    <Input
      placeholder="Enter text..."
      value="This is an input"
      onChange={e => console.log(e.target.value)}
    />
  )
}
```

```jsx
import {Input} from '@shopify/shop-minis-react'

export default function MyComponent() {
  return <Input value="This is an input" />
}
```

```jsx
import {Input} from '@shopify/shop-minis-react'

export default function MyComponent() {
  return <Input disabled value="Disabled input" />
}
```

--------------------------------

### useSecureStorage Hook Example (React)

Source: https://shopify.dev/docs/api/shop-minis/hooks/storage/usesecurestorage

This example demonstrates how to use the `useSecureStorage` hook to get, set, and remove secrets from secure storage within a React component. It utilizes `useEffect` to perform these operations asynchronously.

```javascript
import { useEffect } from 'react'

import { useSecureStorage } from '@shopify/shop-minis-react'

export default function MyComponent() {
  const { getSecret, setSecret, removeSecret } = useSecureStorage()

  useEffect(() => {
    async function handleSecureStorageOperations() {
      // Get a secret from secure storage
      const secret = await getSecret()
      console.log({ secret })

      // Set a secret in secure storage
      await setSecret({ value: 'Sensitive Data' })

      // Remove a secret from secure storage
      await removeSecret()
    }

    handleSecureStorageOperations()
  }, [getSecret, setSecret, removeSecret])
}
```

--------------------------------

### React Navigation with Click Tracking and Confirmation

Source: https://shopify.dev/docs/api/shop-minis/shop-minis/components/TransitionLink

This React component uses the TransitionLink from '@shopify/shop-minis-react' to implement navigation. It includes an example of how to track link clicks for analytics purposes and how to add a confirmation prompt before navigating to the checkout page. Ensure '@shopify/shop-minis-react' is installed as a dependency.

```javascript
import React from 'react'
import {TransitionLink} from '@shopify/shop-minis-react'

function NavigationWithAnalytics() {
  const handleLinkClick = (event: React.MouseEvent<HTMLAnchorElement>) => {
    // Track analytics event
    console.log('Navigation clicked:', event.currentTarget.href)

    // You can prevent navigation by calling event.preventDefault()
    // event.preventDefault()
  }

  return (
    <div>
      <TransitionLink
        to="/products/special-offer"
        onClick={handleLinkClick}
      >
        Special Offer - Click tracking enabled
      </TransitionLink>

      <TransitionLink
        to="/checkout"
        onClick={(e) => {
          // Confirm before navigating
          const confirmed = window.confirm('Proceed to checkout?')
          if (!confirmed) {
            e.preventDefault()
          }
        }}
      >
        Proceed to Checkout
      </TransitionLink>
    </div>
  )
}

export default NavigationWithAnalytics
```

--------------------------------

### Run Shopify Mini Features Command

Source: https://shopify.dev/docs/api/shop-minis/commands/features

Executes the shop-minis features command with various options. This command is used to manage experimental or beta features in your Shopify Mini. Ensure you have the shop-minis CLI installed.

```bash
npx shop-minis features [options]
```

--------------------------------

### React Image Component: Custom Styling

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/image

Example showing how to apply custom styling to the Image component, including setting a custom aspect ratio for responsive layouts.

```javascript
import {Image} from '@shopify/shop-minis-react'

export default function MyComponent() {
  return (
    <Image
      src="https://cdn.shopify.com/example/custom-styled-image.jpg"
      alt="Custom styled image"
      className="w-1/2 mx-auto my-8 rounded-lg shadow-xl"
      aspectRatio={16/9}
    />
  )
}
```

--------------------------------

### Image Upload and Content Creation Example (React)

Source: https://shopify.dev/docs/api/shop-minis/hooks/content/useCreateImageContent

Demonstrates how to use `useCreateImageContent` and `useImagePicker` hooks from '@shopify/shop-minis-react' to capture an image from the camera or gallery and upload it as content. It shows how to handle loading states and potential errors.

```javascript
import {
useCreateImageContent,
useImagePicker,
Button,
} from '@shopify/shop-minis-react'
  
export default function MyComponent() {
const {createImageContent, loading} = useCreateImageContent()
const {openCamera, openGallery} = useImagePicker()
  
const handleCameraCapture = async () => {
try {
const file = await openCamera()
const result = await createImageContent({
image: file,
contentTitle: 'Photo from camera',
visibility: ['DISCOVERABLE', 'LINKABLE'],
})
console.log({data: result.data, userErrors: result.userErrors})
} catch (error) {
console.error('Failed to capture and upload image:', error)
}
}
  
const handleGallerySelect = async () => {
try {
const file = await openGallery()
const result = await createImageContent({
image: file,
contentTitle: 'Photo from gallery',
// Visibility options:
// - ['DISCOVERABLE'] - Appears in Shop recommendations
// - ['LINKABLE'] - Enables shareable URLs
// - ['DISCOVERABLE', 'LINKABLE'] - Both features
// - null or [] - Private within Mini only
visibility: ['DISCOVERABLE', 'LINKABLE'],
})
console.log({data: result.data, userErrors: result.userErrors})
} catch (error) {
console.error('Failed to select and upload image:', error)
}
}

return (
<>
<Button onClick={handleCameraCapture} disabled={loading}>
Take Photo and Upload
</Button>
<Button onClick={handleGallerySelect} disabled={loading}>
Select from Gallery and Upload
</Button>
{loading && <p>Uploading image...</p>}
</>
)
}

```

--------------------------------

### Shopify Shop Minis IconButton Small Size Example

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/iconbutton

Illustrates how to render a small-sized IconButton with a custom icon (Star) and a click handler. This example depends on 'lucide-react' for the icon and '@shopify/shop-minis-react' for the component.

```jsx
import { IconButton } from '@shopify/shop-minis-react'
import { Star } from 'lucide-react'

export default function MyComponent() {
  const handleClick = () => {
    console.log('Small icon button clicked')
  }

  return (
    <IconButton
      Icon={Star}
      size="sm"
      onClick={handleClick}
    />
  )
}
```

--------------------------------

### Shopify Shop Minis IconButton Default and Filled Examples

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/iconbutton

Demonstrates the basic usage of the IconButton component, showing both a default state and a 'filled' state. This component requires the '@shopify/shop-minis-react' library.

```jsx
import React from 'react'
  
import {FavoriteButton} from '@shopify/shop-minis-react'
  
export default function MyComponent() {
return (
<div className="flex items-center gap-4">
<FavoriteButton />
<FavoriteButton filled />
</div>
)
}
```

--------------------------------

### Path Navigation with useNavigateWithTransition

Source: https://shopify.dev/docs/api/shop-minis/shop-minis/hooks/useNavigateWithTransition

Illustrates navigating to different product and category pages, as well as the checkout page with query parameters, using the useNavigateWithTransition hook. This example highlights dynamic route generation and URL parameter usage. It depends on @shopify/shop-minis-react.

```jsx
import React from 'react'
import {useNavigateWithTransition, Button} from '@shopify/shop-minis-react'

function ProductActions({productId}: {productId: string}) {
  const navigateWithTransition = useNavigateWithTransition()

  const handleViewDetails = () => {
    // Navigate to product details page with smooth transition
    navigateWithTransition(`/products/${productId}`)
  }

  const handleViewCategory = (category: string) => {
    // Navigate to category page
    navigateWithTransition(`/categories/${category}`)
  }

  const handleCheckout = () => {
    // Navigate to checkout with query parameters
    navigateWithTransition('/checkout?step=shipping')
  }

  return (
    <div>
      <Button onPress={handleViewDetails}>
        View Product Details
      </Button>
      <Button onPress={() => handleViewCategory('electronics')}>
        Browse Electronics
      </Button>
      <Button onPress={handleCheckout}>
        Proceed to Checkout
      </Button>
    </div>
  )
}

export default ProductActions
```

--------------------------------

### Run Shop Minis Dev Server with Specific Host IP

Source: https://shopify.dev/docs/api/shop-minis/troubleshooting

This command allows you to run the shop-minis development server and explicitly set the host IP address. This can be useful for troubleshooting connection issues, especially when devices are on different network segments or firewalls are interfering. It requires the 'shop-minis' package to be installed.

```bash
npx shop-minis dev --host 192.168.1.100
```

--------------------------------

### Shopify Checkbox Component - Default Usage (React)

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/checkbox

Demonstrates the basic usage of the Checkbox component from '@shopify/shop-minis-react'. This example shows how to import and render a default checkbox.

```javascript
import {Checkbox} from '@shopify/shop-minis-react'
  
export default function MyComponent() {
return <Checkbox checked />
}
```

--------------------------------

### GET /reports/get

Source: https://shopify.dev/docs/api/shop-minis/commands/reports-get

Downloads analytics data for a specific report type and date. Reports are typically in CSV format for easy analysis in spreadsheets or data tools.

```APIDOC
## GET /reports/get

### Description
Downloads analytics data for a specific report type and date. Reports are typically in CSV format for easy analysis in spreadsheets or data tools. Complete the workflow: list → dates → get to access your Mini's analytics.

### Method
GET

### Endpoint
/reports/get

### Parameters
#### Query Parameters
- **report-type** (string) - Required - The report type (see `reports list`).
- **date** (string) - Required - The date for the report in UTC (YYYY-MM-DD format).
- **--output** (string) - Optional - Output file path (defaults to report__.csv).

### Request Example
```bash
npx shop-minis reports get [options] <report-type> <date>
```

### Response
#### Success Response (200)
- **report data** (CSV) - The analytics data for the specified report type and date.

#### Response Example
```csv
Date,Orders,Revenue
2023-10-27,100,5000.00
2023-10-28,120,6000.00
```
```

--------------------------------

### Touchable Component Usage in React

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/touchable

This example demonstrates how to use the 'Touchable' component from '@shopify/shop-minis-react'. It wraps content and provides a visual tap feedback. The component requires importing 'Touchable' and can accept an 'onClick' handler to perform actions when tapped.

```jsx
import {Touchable} from '@shopify/shop-minis-react'
  
export default function MyComponent() {
  const handleClick = () => {
    console.log('Touchable clicked')
  }
  
  return (
    <Touchable onClick={handleClick}>
      <div>Continue</div>
    </Touchable>
  )
}
```

--------------------------------

### Virtualized List with Custom Rendering (React)

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/list

A basic implementation of the virtualized List component using React. It efficiently renders a list of items with customizable content for each item. This example shows how to integrate the `List` component with a `renderItem` function to display simple text-based items.

```javascript
import {List} from '@shopify/shop-minis-react'
  
const sampleItems = [
  {id: '1', title: 'Item 1'},
  {id: '2', title: 'Item 2'},
  {id: '3', title: 'Item 3'},
  {id: '4', title: 'Item 4'},
  {id: '5', title: 'Item 5'},
]
  
export default function MyComponent() {
  const renderItem = (item: (typeof sampleItems)[number]) => (
    <div className="p-4 border-b">
      <span>{item.title}</span>
    </div>
  )
  
  return (
    <List
      items={sampleItems}
      height={300}
      showScrollbar
      renderItem={renderItem}
    />
  )
}
```

--------------------------------

### Virtualized Product List Rendering (React)

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/list

This example demonstrates how to use the `List` component to display a list of product items. It utilizes the `ProductLink` component for rendering individual product information, suitable for e-commerce applications. The `itemSizeForRow` prop is used to define the height of each product item in the list.

```javascript
import {List, ProductLink} from '@shopify/shop-minis-react'

const sampleProducts = [
  {
    id: '1',
    title: 'Sample Product 1',
    price: {amount: '29.99', currencyCode: 'USD'},
    featuredImage: {url: 'https://picsum.photos/200/200', altText: 'Product 1'},
    shop: {id: 'shop1', name: 'Sample Shop'},
    defaultVariantId: 'variant-1',
    isFavorited: false,
  },
  {
    id: '2',
    title: 'Sample Product 2',
    price: {amount: '39.99', currencyCode: 'USD'},
    featuredImage: {url: 'https://picsum.photos/200/200', altText: 'Product 2'},
    shop: {id: 'shop1', name: 'Sample Shop'},
    defaultVariantId: 'variant-2',
    isFavorited: true,
  },
]

export default function MyComponent() {
  const getItemSize = () => 100

  const renderItem = product => (
    <div className="p-4">
      <ProductLink product={product} />
    </div>
  )

  return (
    <List
      items={sampleProducts}
      height={400}
      itemSizeForRow={getItemSize}
      showScrollbar
      renderItem={renderItem}
    />
  )
}
```

--------------------------------

### React Component for Image Upload with Shop Minis API

Source: https://shopify.dev/docs/api/shop-minis/hooks/content/usecreateimagecontent

An example React component demonstrating how to use `useCreateImageContent` and `useImagePicker` hooks from '@shopify/shop-minis-react'. It allows users to capture images via the camera or select them from the gallery and upload them. The component handles loading states and logs results or errors.

```javascript
import {
useCreateImageContent,
useImagePicker,
Button,
} from '@shopify/shop-minis-react'
  
export default function MyComponent() {
const {createImageContent, loading} = useCreateImageContent()
const {openCamera, openGallery} = useImagePicker()
  
const handleCameraCapture = async () => {
try {
const file = await openCamera()
const result = await createImageContent({
image: file,
contentTitle: 'Photo from camera',
visibility: ['DISCOVERABLE', 'LINKABLE'],
})
console.log({data: result.data, userErrors: result.userErrors})
} catch (error) {
console.error('Failed to capture and upload image:', error)
}
}
  
const handleGallerySelect = async () => {
try {
const file = await openGallery()
const result = await createImageContent({
image: file,
contentTitle: 'Photo from gallery',
// Visibility options:
// - ['DISCOVERABLE'] - Appears in Shop recommendations
// - ['LINKABLE'] - Enables shareable URLs
// - ['DISCOVERABLE', 'LINKABLE'] - Both features
// - null or [] - Private within Mini only
visibility: ['DISCOVERABLE', 'LINKABLE'],
})
console.log({data: result.data, userErrors: result.userErrors})
} catch (error) {
console.error('Failed to select and upload image:', error)
}
}

return (
<>
<Button onClick={handleCameraCapture} disabled={loading}>
Take Photo and Upload
</Button>
<Button onClick={handleGallerySelect} disabled={loading}>
Select from Gallery and Upload
</Button>
{loading && <p>Uploading image...</p>}
</>
)
}
```

--------------------------------

### List Available Report Types using Shop Minis CLI

Source: https://shopify.dev/docs/api/shop-minis/commands/reports-list

This command lists all available analytics report types for your Shopify Mini. Use this to understand the kinds of insights you can gain before specifying dates or downloading specific reports. It requires the shop-minis CLI to be installed.

```bash
npx shop-minis reports list
```

--------------------------------

### Shopify Shop Minis IconButton Large Size Example

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/iconbutton

Demonstrates the usage of a large-sized IconButton, using a Settings icon and defining a click event. This snippet requires 'lucide-react' for the icon and '@shopify/shop-minis-react' for the IconButton component.

```jsx
import { IconButton } from '@shopify/shop-minis-react'
import { Settings } from 'lucide-react'

export default function MyComponent() {
  const handleClick = () => {
    console.log('Large icon button clicked')
  }

  return <IconButton Icon={Settings} size="lg" onClick={handleClick} />
}
```

--------------------------------

### Destructive Badge Styling (React)

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/badge

Provides a React code example for the destructive variant of the Badge component from '@shopify/shop-minis-react'. This styling is intended for warnings or error indicators.

```jsx
import {Badge} from '@shopify/shop-minis-react'

export default function MyComponent() {
  return <Badge variant="destructive">Destructive</Badge>
}


```

--------------------------------

### Download Report by Type and Date (CLI)

Source: https://shopify.dev/docs/api/shop-minis/commands/reports-get

This command downloads analytics data for a specific report type and date. Reports are typically in CSV format. It requires the report type and date as arguments and optionally accepts an output file path. The date must be in UTC YYYY-MM-DD format.

```bash
npx shop-minis reports get [options] <report-type> <date>
```

--------------------------------

### Forward Android ADB Port for Mini Development

Source: https://shopify.dev/docs/api/shop-minis/troubleshooting

This command uses Android Debug Bridge (ADB) to forward traffic from a specific port on the Android device to a corresponding port on the development machine. This is crucial for allowing the Shopify Shop app on an Android device to connect to the Mini's development server, overcoming potential network restrictions. It requires ADB to be installed and configured, and the Android device to be connected via USB with developer options enabled.

```bash
adb reverse tcp:5173 tcp:5173
```

--------------------------------

### Styled TransitionLink with Custom Classes and Styles

Source: https://shopify.dev/docs/api/shop-minis/shop-minis/components/TransitionLink

Illustrates how to apply custom CSS classes and inline styles to TransitionLink components for distinct visual appearances. This example shows styling for a product details link and a shopping cart link, including adding a cart count indicator.

```javascript
import React from 'react'
import {TransitionLink} from '@shopify/shop-minis-react'

function StyledNavigation() {
  return (
    <nav className="navigation">
      <TransitionLink
        to="/products/123"
        className="product-link"
        style={{ color: '#007AFF', textDecoration: 'none' }}
      >
        View Product Details
      </TransitionLink>

      <TransitionLink
        to="/cart"
        className="cart-link"
        aria-label="Go to shopping cart"
      >
        <span>Shopping Cart</span>
        <span className="cart-count">(3)</span>
      </TransitionLink>
    </nav>
  )
}

export default StyledNavigation

```

--------------------------------

### Interact with Secure Storage using useSecureStorage Hook

Source: https://shopify.dev/docs/api/shop-minis/hooks/storage/useSecureStorage

Demonstrates how to use the `useSecureStorage` hook to get, set, and remove secrets from secure storage. This hook is suitable for sensitive data requiring hardware-backed encryption. It returns functions `getSecret`, `setSecret`, and `removeSecret`.

```javascript
import { useEffect } from 'react';
import { useSecureStorage } from '@shopify/shop-minis-react';

export default function MyComponent() {
  const { getSecret, setSecret, removeSecret } = useSecureStorage();

  useEffect(() => {
    async function handleSecureStorageOperations() {
      // Get a secret from secure storage
      const secret = await getSecret();
      console.log({ secret });

      // Set a secret in secure storage
      await setSecret({ value: 'Sensitive Data' });

      // Remove a secret from secure storage
      await removeSecret();
    }

    handleSecureStorageOperations();
  }, [getSecret, setSecret, removeSecret]);
}
```

--------------------------------

### Crafting an Effective Mini Description

Source: https://shopify.dev/docs/api/shop-minis/manifest-file

The `description` field provides a concise summary of your Mini's purpose, displayed to users in the Shop app to aid discovery and understanding. Aim for 30-50 characters, using action-oriented language to highlight the unique value proposition and key features.

```json
{
  "description": "Track your outfits every day"
}
```

--------------------------------

### Submit Shop Mini for Review (CLI)

Source: https://shopify.dev/docs/api/shop-minis/commands/submit

The primary command to submit your Shop Mini for review. It runs checks and validation before uploading. Accepts options for describing changes and enabling debug messages.

```bash
npx shop-minis submit [options]
```

--------------------------------

### Shop Mini Permissions Configuration

Source: https://shopify.dev/docs/api/shop-minis/manifest-file

Defines the native device capabilities your Shop Mini requires. Permissions are requested from the user when your Mini attempts to use them, such as accessing the camera or microphone. Only essential permissions should be requested to avoid review delays.

```json
{
  "permissions": ["CAMERA", "MICROPHONE"]
}
```

--------------------------------

### Navigate with Transitions using useNavigateWithTransition

Source: https://shopify.dev/docs/api/shop-minis/shop-minis/hooks/usenavigatewithtransition

Demonstrates using the useNavigateWithTransition hook for programmatic navigation, including navigating to a specific product and going back in history. Requires @shopify/shop-minis-react.

```javascript
import {useNavigateWithTransition, Button} from '@shopify/shop-minis-react'
  
export default function MyComponent() {
const transitionNavigate = useNavigateWithTransition()
  
const handleProductClick = () => {
transitionNavigate('/products/123')
}
  
const handleGoBack = () => {
transitionNavigate(-1)
}
  
return (
<>
<Button onClick={handleProductClick}>View Product</Button>
<Button onClick={handleGoBack}>Go Back</Button>
</>
)
}
```

--------------------------------

### Path Navigation with Smooth Transitions

Source: https://shopify.dev/docs/api/shop-minis/shop-minis/hooks/usenavigatewithtransition

Illustrates navigating to specific routes, including product details, categories, and checkout with query parameters, using the useNavigateWithTransition hook for a smooth transition experience. It depends on @shopify/shop-minis-react.

```javascript
import React from 'react'
import {useNavigateWithTransition, Button} from '@shopify/shop-minis-react'
  
function ProductActions({productId}: {productId: string}) {
const navigateWithTransition = useNavigateWithTransition()
  
const handleViewDetails = () => {
// Navigate to product details page with smooth transition
navigateWithTransition(`/products/${productId}`)
}
  
const handleViewCategory = (category: string) => {
// Navigate to category page
navigateWithTransition(`/categories/${category}`)
}
  
const handleCheckout = () => {
// Navigate to checkout with query parameters
navigateWithTransition('/checkout?step=shipping')
}
  
return (
<div>
<Button onPress={handleViewDetails}>
View Product Details
</Button>
<Button onPress={() => handleViewCategory('electronics')}>
Browse Electronics
</Button>
<Button onPress={handleCheckout}>
Proceed to Checkout
</Button>
</div>
)
}
  
export default ProductActions
```

--------------------------------

### Interface for Getting an Async Storage Item

Source: https://shopify.dev/docs/api/shop-minis/hooks/storage/useAsyncStorage

Defines the parameter object required for the `getItem` function within the `useAsyncStorage` hook, specifying the key of the item to retrieve.

```typescript
export interface GetAsyncStorageItemParams {
  key: string
}
```

--------------------------------

### Basic Navigation Controls with useNavigateWithTransition

Source: https://shopify.dev/docs/api/shop-minis/shop-minis/hooks/useNavigateWithTransition

Demonstrates basic navigation using `useNavigateWithTransition` for moving back or forward in the browser history. It utilizes the hook to navigate by a specified number of steps (e.g., -1 for back, 1 for forward).

```javascript
import React from 'react'
import {useNavigateWithTransition, Button} from '@shopify/shop-minis-react'

function NavigationControls() {
  const navigateWithTransition = useNavigateWithTransition()

  const handleGoBack = () => {
    // Navigate back one page in history with smooth transition
    navigateWithTransition(-1)
  }

  const handleGoBackTwo = () => {
    // Navigate back two pages
    navigateWithTransition(-2)
  }

  const handleGoForward = () => {
    // Navigate forward one page in history
    navigateWithTransition(1)
  }

  return (
    <div className="navigation-controls">
      <Button onPress={handleGoBack}>
        Back
      </Button>
      <Button onPress={handleGoBackTwo}>
        Back to Home
      </Button>
      <Button onPress={handleGoForward}>
        Forward
      </Button>
    </div>
  )
}

export default NavigationControls
```

--------------------------------

### React Image Component: With Thumbhash Placeholder

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/image

Demonstrates the use of `thumbhash` for progressive image loading. A low-quality placeholder is shown initially, improving to the full image once loaded.

```javascript
import {Image} from '@shopify/shop-minis-react'

export default function MyComponent() {
  return (
    <Image
      src="https://cdn.shopify.com/example/large-image.jpg"
      thumbhash="HBkSHYSIeHiPiHh8eJd4eTN0D3"
      alt="Product with placeholder"
      className="w-full rounded-lg"
      onLoad={() => console.log('Image loaded')}
    />
  )
}
```

--------------------------------

### Disabled QuantitySelector State (React)

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/quantityselector

This example demonstrates how to disable the QuantitySelector component, making it non-interactive. The 'disabled' prop is a boolean that, when set to true, prevents any changes to the quantity. The 'onQuantityChange' callback will not be triggered when disabled.

```javascript
import {QuantitySelector} from '@shopify/shop-minis-react'

export default function MyComponent() {
  const handleQuantityChange = newQuantity => {
    console.log('Quantity changed to:', newQuantity)
  }

  return (
    <QuantitySelector
      quantity={3}
      onQuantityChange={handleQuantityChange}
      maxQuantity={10}
      disabled
    />
  )
}
```

--------------------------------

### React Image Component: Default Usage

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/image

Demonstrates the basic usage of the Image component, rendering a remote image with specified source, alt text, thumbhash for progressive loading, and aspect ratio.

```javascript
import React from 'react'
  
import {Image} from '@shopify/shop-minis-react'
  
export default function MyComponent() {
return (
<Image
src="https://images.unsplash.com/photo-1551524164-687a55dd1126?w=400&h=400&fit=crop&crop=center"
alt="The Hero Snowboard"
thumbhash="NwgGBQD3qIt2+EkWqHqGV4tgd0EH"
aspectRatio={1}
/>
)
}
```

--------------------------------

### QuantitySelector with Max Value (React)

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/quantityselector

This example shows how to configure the QuantitySelector with a maximum allowable quantity. It uses the 'maxQuantity' prop to set the upper limit for the quantity adjustment. The 'onQuantityChange' callback is essential for receiving updates.

```javascript
import {QuantitySelector} from '@shopify/shop-minis-react'

export default function MyComponent() {
  const handleQuantityChange = newQuantity => {
    console.log('Quantity changed to:', newQuantity)
  }

  return (
    <QuantitySelector
      quantity={1}
      onQuantityChange={handleQuantityChange}
      maxQuantity={10}
    />
  )
}
```

--------------------------------

### Basic TransitionLink Usage in React

Source: https://shopify.dev/docs/api/shop-minis/shop-minis/components/transitionlink

Demonstrates the basic implementation of TransitionLink for navigation within a Shopify Mini application. It requires importing TransitionLink and MinisRouter from '@shopify/shop-minis-react' and setting up Routes and Route from 'react-router'. View transitions must be enabled in MinisRouter for animations to function.

```jsx
import React from 'react'
import {MinisRouter, TransitionLink} from '@shopify/shop-minis-react'
import {Routes, Route} from 'react-router'
  
function Navigation() {
  return (
    <nav>
      <TransitionLink to="/">Home</TransitionLink>
      <TransitionLink to="/products">Products</TransitionLink>
      <TransitionLink to="/cart">Cart</TransitionLink>
    </nav>
  )
}
  
function App() {
  return (
    <div>
      <MinisRouter viewTransitions>
        <Routes>
          <Route path="/" element={<Navigation />} />
        </Routes>
      </MinisRouter>
    </div>
  )
}
  
export default App
  
```

--------------------------------

### Enable a Specific Feature using shop-minis CLI

Source: https://shopify.dev/docs/api/shop-minis/commands/features

Enables a particular experimental or beta feature in your Shopify Mini. Replace 'feature-name' with the actual name of the feature you wish to enable. This allows testing of upcoming SDK capabilities.

```bash
npx shop-minis features --enable feature-name
```

--------------------------------

### Use Generate User Token Hook in React

Source: https://shopify.dev/docs/api/shop-minis/hooks/usegenerateusertoken

This example demonstrates how to use the useGenerateUserToken hook within a React component. It generates a temporary user token and logs the token, expiration time, and user state to the console. The generated token can be used to authenticate requests to your backend.

```javascript
import { useCallback } from 'react';
import { useGenerateUserToken, Button } from '@shopify/shop-minis-react';

export default function MyComponent() {
  const { generateUserToken } = useGenerateUserToken();

  const performRequest = useCallback(async () => {
    const { data } = await generateUserToken();
    const { token, expiresAt, userState } = data;

    console.log({ token, expiresAt, userState });
  }, [generateUserToken]);

  return <Button onPress={performRequest} text="Perform request" />;
}
```

--------------------------------

### Shopify Select Component - React

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/select

Demonstrates the basic usage of the Shopify Select component. This component allows users to select an option from a dropdown list. It requires importing several components from '@shopify/shop-minis-react'. The output is a selectable dropdown.

```jsx
import {Select, SelectContent, SelectItem, SelectTrigger, SelectValue} from '@shopify/shop-minis-react'
  
export default function MyComponent() {
return (
<Select defaultValue="option-1">
<SelectTrigger>
<SelectValue placeholder="Select an option" />
</SelectTrigger>
<SelectContent>
<SelectItem value="option-1">Option 1</SelectItem>
<SelectItem value="option-2">Option 2</SelectItem>
<SelectItem value="option-3">Option 3</SelectItem>
</SelectContent>
</Select>
)
}
```

--------------------------------

### Shopify Card Component Implementation (React)

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/card

Demonstrates the basic structure and usage of the Shopify Card component. This component is built using React and requires the '@shopify/shop-minis-react' library. It includes CardHeader, CardContent, and CardFooter for organizing information.

```jsx
import {Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent} from '@shopify/shop-minis-react'
  
export default function MyComponent() {
return (
<Card>
<CardHeader>
<CardTitle>Card Title</CardTitle>
<CardDescription>Card description goes here</CardDescription>
</CardHeader>
<CardContent>
<p>This is the main content of the card.</p>
</CardContent>
<CardFooter>
<p>Card footer content</p>
</CardFooter>
</Card>
)
}
```

--------------------------------

### Use Async Storage Hook and Operations

Source: https://shopify.dev/docs/api/shop-minis/hooks/storage/useAsyncStorage

This snippet demonstrates how to use the `useAsyncStorage` hook to perform common storage operations: getting an item, setting an item, removing an item, retrieving all keys, and clearing all items. It utilizes `useEffect` to manage these asynchronous operations within a React component.

```javascript
import {useEffect} from 'react'

import {useAsyncStorage} from '@shopify/shop-minis-react'

export default function MyComponent() {
  const {getItem, setItem, removeItem, getAllKeys, clear} = useAsyncStorage()

  useEffect(() => {
    async function handleStorageOperations() {
      // Get an item from storage
      const value = await getItem({key: 'myKey'})
      console.log({value})

      // Set an item in storage
      await setItem({key: 'myKey', value: 'Hello, World!'})

      // Remove an item from storage
      await removeItem({key: 'myKey'})

      // Get all keys in storage
      const keys = await getAllKeys()
      console.log({keys})

      // Clear all items from storage
      await clear()
    }

    handleStorageOperations()
  }, [getItem, removeItem, setItem, getAllKeys, clear])
}
```

--------------------------------

### Implement AlertDialog with Customizable Actions

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/alertdialog

Demonstrates how to use the AlertDialog component from @shopify/shop-minis-react to create a confirmation dialog. It includes importing necessary components, defining a confirmation handler, and structuring the dialog with a trigger, content, header, title, description, and footer with cancel and action buttons. The action button executes a callback function upon click.

```javascript
import {
 AlertDialog,
 AlertDialogAction,
 AlertDialogCancel,
 AlertDialogContent,
 AlertDialogDescription,
 AlertDialogFooter,
 AlertDialogHeader,
 AlertDialogTitle,
 AlertDialogTrigger,
 Button,
} from '@shopify/shop-minis-react'

export default function MyComponent() {
 const handleConfirm = () => {
 console.log('Confirmed')
 }

 return (
 <AlertDialog>
 <AlertDialogTrigger asChild>
 <Button variant="outline">Show Dialog</Button>
 </AlertDialogTrigger>
 <AlertDialogContent>
 <AlertDialogHeader>
 <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
 <AlertDialogDescription>
 This action cannot be undone. This will permanently delete your
 account and remove your data from our servers.
 </AlertDialogDescription>
 </AlertDialogHeader>
 <AlertDialogFooter>
 <AlertDialogCancel>Cancel</AlertDialogCancel>
 <AlertDialogAction onClick={handleConfirm}>
 Continue
 </AlertDialogAction>
 </AlertDialogFooter>
 </AlertDialogContent>
 </AlertDialog>
 )
}
```

--------------------------------

### Shop Mini Scopes Configuration

Source: https://shopify.dev/docs/api/shop-minis/manifest-file

Specifies the user data your Shop Mini can access via the Shop Minis SDK. Certain SDK hooks require specific scopes to be declared in the manifest before use. Follow the principle of least privilege and only request necessary scopes.

```json
{
  "scopes": ["profile", "orders"]
}
```

--------------------------------

### Shopify Shop Minis React Progress Component Usage

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/progress

Demonstrates the basic usage of the Progress component from '@shopify/shop-minis-react'. This component is used to show completion status or loading progress. It takes a 'value' prop to indicate the current progress percentage.

```javascript
import {Progress} from '@shopify/shop-minis-react'
  
export default function MyComponent() {
return <Progress value={50} />
}
```

--------------------------------

### useCreateImageContent Hook API

Source: https://shopify.dev/docs/api/shop-minis/hooks/content/usecreateimagecontent

This section details the useCreateImageContent hook, its return values, parameters for creating content, and the structure of the returned content objects.

```APIDOC
## useCreateImageContent Hook

### Description
The `useCreateImageContent` hook combines image upload with content creation to generate user-generated content entries. It handles the image upload pipeline and content entity creation in a single operation, automatically associating content with your Mini and integrating with Shop's content systems.

**Caution:** You must run the `setup` CLI command before using this hook so the content can be associated with the Mini.

### Method
This is a React hook, not an HTTP method.

### Returns
- **createImageContent** (`function`): An asynchronous function that uploads an image and creates content. It returns a Promise that resolves to an object containing the created `data` and any `userErrors`.
  - **Parameters**: Accepts a `CreateImageContentParams` object.
  - **Returns**: `Promise<{ data: Content; userErrors?: ContentCreateUserErrors[]; }>`
- **loading** (`boolean`): Indicates whether the content creation process is currently in progress.

### CreateImageContentParams
This interface defines the parameters required for the `createImageContent` function.

- **image** (`File`): The image file to upload.
- **contentTitle** (`string`): The title for the content entry.
- **visibility** (`ContentVisibility[] | null`): An optional array of visibility settings. Defaults to private if not provided.

### ContentVisibility Options
- **`DISCOVERABLE`**: Makes content eligible for Shop's recommendation and discovery systems.
- **`LINKABLE`**: Enables shareable URLs for the content.

### Content Object Structure
Represents a created content entry.

- **publicId** (`string`): The unique public identifier for the content.
- **externalId** (`string | null`): An optional external identifier.
- **image** (`ContentImage`): Information about the content's image.
- **title** (`string`): The title of the content.
- **description** (`string | null`): An optional description for the content.
- **visibility** (`ContentVisibility[]`): The visibility settings applied to the content.
- **shareableUrl** (`string | null`): The URL to share the content, if `LINKABLE` visibility is set.
- **products** (`ContentProduct[] | null`): An optional array of products associated with the content.
- **status** (`MinisContentStatus | null`): The current status of the content.

### ContentImage Object Structure
Provides details about the image associated with the content.

- **id** (`string | null`): The image's unique identifier.
- **url** (`string`): The URL of the image.
- **width** (`number | null`): The width of the image in pixels.
- **height** (`number | null`): The height of the image in pixels.
- **thumbhash** (`string | null`): A thumbhash representation of the image.
- **altText** (`string | null`): Alternative text for the image.

### ContentProduct Object Structure
Represents a product associated with the content.

- **id** (`string`): The product's unique identifier.
- **title** (`string`): The title of the product.
- **featuredImage** (`ContentImage | null`): Information about the product's featured image.

### MinisContentStatus Enum
Defines the possible statuses for content entries.

- **`PENDING`**: The content is awaiting processing.
- **`READY`**: The content is ready and publicly available (based on visibility settings).
- **`REJECTED`**: The content has been rejected.
```

--------------------------------

### Shopify Button Component - Default Usage

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/button

Demonstrates the basic usage of the Shopify Button component. It requires the '@shopify/shop-minis-react' library. The component accepts an onClick handler and child content for the button text.

```jsx
import {Button} from '@shopify/shop-minis-react'
  
export default function MyComponent() {
  const handleClick = () => {
    console.log('Button pressed')
  }
  
  return <Button onClick={handleClick}>Continue</Button>
}
```

--------------------------------

### Generate API Key using Shopify CLI

Source: https://shopify.dev/docs/api/shop-minis/commands/api-keys-generate

Generates a new API key for your Mini to authenticate with Shop APIs. The generated key should be stored securely as it will not be shown again. Multiple keys can be used for different environments or rotated regularly for security.

```bash
npx shop-minis api-keys generate [options]
```

--------------------------------

### Badge Component Usage with Variants (React)

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/badge

Demonstrates how to use the Badge component from '@shopify/shop-minis-react' with different visual variants. It requires React and the shop-minis-react library. The input is JSX, and the output is a set of styled badge elements.

```jsx
import React from 'react'
  
import {Badge} from '@shopify/shop-minis-react'
  
export default function MyComponent() {
return (
<div className="flex flex-wrap gap-2">
<Badge>Default</Badge>
<Badge variant="secondary">Secondary</Badge>
<Badge variant="destructive">Destructive</Badge>
<Badge variant="outline">Outline</Badge>
</div>
)
}
  
```

--------------------------------

### List Report Dates using shop-minis CLI

Source: https://shopify.dev/docs/api/shop-minis/commands/reports-dates

This command lists available dates for a specified Shopify report type. It requires a `report-type` argument (e.g., CONTENT_IMPRESSIONS, SALES) and can optionally use the `--raw` flag to display dates without headers or formatting. Note that the most recent data may be 1-2 days old due to daily report generation and processing delays.

```bash
npx shop-minis reports dates [options] <report-type>
```

```bash
npx shop-minis reports dates --raw SALES
```

--------------------------------

### Programmatic Navigation with useNavigateWithTransition

Source: https://shopify.dev/docs/api/shop-minis/shop-minis/hooks/useNavigateWithTransition

Demonstrates basic usage of the useNavigateWithTransition hook for navigating to specific routes and back in the history. Requires @shopify/shop-minis-react. The hook returns a function that takes a route path or a history step (e.g., -1) as an argument.

```jsx
import {useNavigateWithTransition, Button} from '@shopify/shop-minis-react'

export default function MyComponent() {
  const transitionNavigate = useNavigateWithTransition()

  const handleProductClick = () => {
    transitionNavigate('/products/123')
  }

  const handleGoBack = () => {
    transitionNavigate(-1)
  }

  return (
    <>
      <Button onClick={handleProductClick}>View Product</Button>
      <Button onClick={handleGoBack}>Go Back</Button>
    </>
  )
}
```

--------------------------------

### Shopify Shop Minis React Alert Component - Default Variant

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/alert

This code snippet demonstrates how to use the default variant of the Alert component from '@shopify/shop-minis-react'. It displays a title and a description for general notifications. This component requires importing Alert, AlertTitle, and AlertDescription from the library.

```javascript
import {Alert, AlertTitle, AlertDescription} from '@shopify/shop-minis-react'

export default function MyComponent() {
  return (
    <Alert variant="default">
      <AlertTitle>Heads up!</AlertTitle>
      <AlertDescription>
        You can add components to your app using our SDK.
      </AlertDescription>
    </Alert>
  )
}
```

--------------------------------

### Shop Mini Trusted Domains Configuration

Source: https://shopify.dev/docs/api/shop-minis/manifest-file

Lists the external domains your Shop Mini is permitted to communicate with. This is a crucial security feature restricting network requests, image sources, video sources, and other external resources to approved domains only.

```json
{
  "trusted_domains": [
    "example.com",
    "api.example.com/v1"
  ]
}
```

--------------------------------

### QuantitySelector Component Usage (React)

Source: https://shopify.dev/docs/api/shop-minis/components/primitives/quantityselector

Demonstrates the basic implementation of the QuantitySelector component. It requires the 'QuantitySelector' import from '@shopify/shop-minis-react'. The component takes an initial quantity and a callback function to handle quantity changes, along with an optional maximum quantity.

```javascript
import {QuantitySelector} from '@shopify/shop-minis-react'
  
export default function MyComponent() {
const handleQuantityChange = newQuantity => {
console.log('Quantity changed to:', newQuantity)
}
  
return (
<QuantitySelector
quantity={1}
onQuantityChange={handleQuantityChange}
maxQuantity={10}
/>
)
}
```
Tokens:
Raw