Putting it together: a free-shipping progress bar

{
  "settings": [
    {
      "id": "free_shipping_min",
      "type": "string",
      "format": "text",
      "icon": "sicon-shipping-fast",
      "label": "Free shipping from (SAR). Leave empty to hide the bar.",
      "value": "",
      "required": false
    }
  ]
}

// app/types/theme-settings.d.ts
export {}; // keeps this file a module, so the block below adds to the engine's type

declare module '@salla.sa/twilight-theme-engine/types' {
  interface ThemeSettings {
    free_shipping_min?: string; // the id from twilight.json
  }
}

// app/hooks/useCartSubtotal.ts
import { useEffect, useState } from 'react';
import { getSallaSDK } from '@salla.sa/twilight-theme-engine/utils';

export function useCartSubtotal() {
  const [subtotal, setSubtotal] = useState<number | null>(null);

  useEffect(() => {
    const salla = getSallaSDK(); // undefined on the server
    if (!salla) return;
    let active = true;
    const onUpdated = (...args: unknown[]) => {
      const summary = args[0] as { sub_total?: number } | undefined;
      if (typeof summary?.sub_total === 'number') setSubtotal(summary.sub_total);
    };

    salla
      .onReady()
      .then(() => {
        if (!active) return;
        const stored = salla.storage.get('cart.summary') as { sub_total?: number } | undefined;
        setSubtotal(typeof stored?.sub_total === 'number' ? stored.sub_total : 0);
        salla.cart.event?.onUpdated?.(onUpdated);
      })
      .catch(() => undefined);

    return () => {
      active = false;
      salla.cart.event?.offUpdated?.(onUpdated); // the same function
    };
  }, []);

  return subtotal;
}

// app/components/cart/FreeShipping.tsx
import { useMoney } from '@salla.sa/twilight-theme-engine/hooks/useMoney';
import { useTheme } from '@salla.sa/twilight-theme-engine/hooks/useTheme';
import { useTranslation } from '@salla.sa/twilight-theme-engine/i18n';
import { useCartSubtotal } from '../../hooks/useCartSubtotal';

export function FreeShippingBar({ threshold, subtotal }: { threshold: number; subtotal: number }) {
  const { format } = useMoney();
  const { t } = useTranslation();
  const { color } = useTheme();
  const remaining = Math.max(0, threshold - subtotal);
  const percent = Math.min(100, Math.round((subtotal / threshold) * 100));
  // Salla's message is HTML with a :amount placeholder: keep the words, put the price in JSX.
  const [before, after = ''] = t('pages.cart.free_shipping_alert', 'Add :amount more for free shipping')
    .replace(/<[^>]+>/g, '')
    .replace(/\s+/g, ' ')
    .split(':amount');

  return (
    <div className="free-shipping">
      <p>
        <i className="sicon-shipping-fast" />{' '}
        {remaining === 0 ? (
          t('pages.cart.has_free_shipping', 'You have free shipping!')
        ) : (
          <>
            {before}
            <strong>{format(remaining)}</strong>
            {after}
          </>
        )}
      </p>
      <div role="progressbar" aria-valuemin={0} aria-valuemax={100} aria-valuenow={percent}>
        <div style={{ width: `${percent}%`, background: color.primary }} />
      </div>
    </div>
  );
}

export function CartFreeShipping({ threshold }: { threshold: number }) {
  const subtotal = useCartSubtotal();
  if (subtotal === null) return null; // the server, and the moment before the SDK is ready
  return <FreeShippingBar threshold={threshold} subtotal={subtotal} />;
}

// app/hooks/index.tsx
import { hookRegistry, HookName, type HookContext } from '@salla.sa/twilight-theme-engine/hooks';
import { CartFreeShipping } from '../components/cart/FreeShipping';

let registered = false;

export function registerThemeHooks() {
  if (registered) return;
  registered = true;

  hookRegistry.register(HookName.CART_SUMMARY_START, ({ twilight }: HookContext) => {
    const threshold = Number(twilight.theme.settings.free_shipping_min);
    if (!threshold) return null; // not set by the merchant: show nothing
    return <CartFreeShipping threshold={threshold} />;
  });
}