Skip to main content

partner.addAccessoryButton

Adds an icon + label accessory button to the top navigation bar. Tap events are received via tdsEvent.addEventListener("navigationAccessoryEvent", callback).

Signature​

addAccessoryButton is exposed as a member of the partner namespace object. It is not imported as a standalone function.

import { partner } from '@apps-in-toss/web-framework';

type AddAccessoryButtonOptions = {
  id: string;
  title: string;
  icon: {
    name: string;
  };
};

declare const partner: {
  addAccessoryButton(options: AddAccessoryButtonOptions): Promise<void>;
};

Parameters​

NameTypeRequiredDescription
optionsAddAccessoryButtonOptions✓Button configuration object.
options.idstring✓Unique identifier for the button. Used to distinguish which button was tapped in the event listener.
options.titlestring✓Label text displayed on the button.
options.icon.namestring✓Icon name. Use design-system icon tokens.

Returns​

  • Promise<void> — resolves once the button has been added.

Permission​

No permission required — partner.addAccessoryButton is not bound to any PermissionName. For how other namespaces handle permissions, see Guides — Permissions pattern.

Examples​

Minimal​

import { partner } from '@apps-in-toss/web-framework';

await partner.addAccessoryButton({
  id: 'btn-favorite',
  title: 'Favorite',
  icon: { name: 'icon-star-mono' },
});

Realistic — tap event and cleanup​

import { partner, tdsEvent } from '@apps-in-toss/web-framework';
import { useEffect } from 'react';

function ProductDetailPage() {
  useEffect(() => {
    const BUTTON_ID = 'btn-favorite';

    partner.addAccessoryButton({
      id: BUTTON_ID,
      title: 'Favorite',
      icon: { name: 'icon-star-mono' },
    });

    const unsubscribe = tdsEvent.addEventListener(
      'navigationAccessoryEvent',
      (event) => {
        if (event.id === BUTTON_ID) {
          console.log('Favorite button tapped');
        }
      },
    );

    return () => {
      // Clean up the button and listener when leaving the screen.
      partner.removeAccessoryButton();
      unsubscribe();
    };
  }, []);

  return <main>{/* page content */}</main>;
}

Try it live​

Run partner.addAccessoryButton in the Partner page of sdk-example.

Open in sdk-example
  • Guides — Accessory button UX — lifecycle of addAccessoryButton/removeAccessoryButton paired with navigationAccessoryEvent, id routing, multi-button screens, and state toggles in one place.

External references​