[{"value":"Quick start","id":"quick-start","hLevel":2,"level":1},{"value":"API methods","id":"api-methods","hLevel":2,"level":1,"children":[{"value":"trigger()","id":"trigger","hLevel":3,"level":2},{"value":"exit()","id":"exit","hLevel":3,"level":2}]},{"value":"Examples","id":"examples","hLevel":2,"level":1,"children":[{"value":"Example 1: Data loading","id":"example-1-data-loading","hLevel":3,"level":2},{"value":"Example 2: Form save","id":"example-2-form-save","hLevel":3,"level":2}]},{"value":"Important notes","id":"important-notes","hLevel":2,"level":1,"children":[{"value":"Always use trigger() and exit() together","id":"always-use-trigger-and-exit-together","hLevel":3,"level":2},{"value":"Avoid repeated use","id":"avoid-repeated-use","hLevel":3,"level":2}]}]

Loading

Loading is a component for displaying a global loading state. By showing a progress bar animation at the top of the SHOPLINE Admin, it informs merchants that the app is processing a request or loading data. This helps effectively manage expectations, letting merchants know the app's response status and preventing uncertainty due to waiting.

Quick start

The following example demonstrates the basic implementation of the Loading component:

import Client, { Loading, shared } from '@shoplineos/app-bridge';
// 1. Initialize App Bridge.
const app = Client.createApp({
  appKey: 'your-app-key',
  host: shared.getHost(),
});
// 2. Create a Loading instance.
const loading = Loading.create(app);
// 3. Show loading state.
loading.trigger();
setTimeout(() => {
  loading.exit();
}, 2000);

After you call the trigger() method, a loading progress bar will appear at the top of the page. The effect is as follows:

API methods

trigger()

(): void

Starts showing the loading state.

Example

// Show loading state.
loading.trigger();

exit()

(): void

Ends and hides the loading state.

Example

// Hide loading state.
loading.exit();

Examples

Example 1: Data loading

import Client, { Loading, shared } from '@shoplineos/app-bridge';
const app = Client.createApp({
  appKey: 'your-app-key',
  host: shared.getHost(),
});
const loading = Loading.create(app);
// Load product data.
const fetchProducts = async () => {
  // Show loading state.
  loading.trigger();
  try {
    const response = await fetch('/api/products');
    const products = await response.json();
    // Process data.
    console.log('Product data:', products);
  } catch (error) {
    console.error('Loading failed:', error);
  } finally {
    loading.exit();
  }
};
fetchProducts();

Example 2: Form save

const handleSave = async (formData) => {
  // Show loading state.
  loading.trigger();
  try {
    // Submit form data.
    await saveProduct(formData);
    // Save was successful.
    console.log('Save successful.');
  } catch (error) {
    // Save failed.
    console.error('Save failed:', error);
  } finally {
    // End loading state.
    loading.exit();
  }
};

Important notes

Always use `trigger()` and `exit()` together

Every call to trigger() must be followed by a corresponding call to exit(). Otherwise, the loading state will persist, negatively impacting the user experience.

// Recommended: Use try-finally to ensure that exit() is called.
const loadData = async () => {
  loading.trigger();
  try {
    await fetchData();
  } finally {
    loading.exit(); // Execute regardless of success or failure.
  }
};

Avoid repeated use

Do not call trigger() repeatedly when the loading state is already showing, as this may prevent the loading state from closing correctly.

// Not recommended: Repeated use
loading.trigger();
loading.trigger(); // Avoid repeated calls.
loading.exit(); // May not close correctly.
// Recommended: Use a flag for control
let isLoading = false;
const loadData = async () => {
  if (isLoading) return;
  isLoading = true;
  loading.trigger();
  try {
    await fetchData();
  } finally {
    loading.exit();
    isLoading = false;
  }
};