Skip to main content

graniteEvent.addEventListener

Subscribes to Granite (Toss internal UI framework) events. Currently supports backEvent (hardware/software back button) and homeEvent (home button). Returns a cleanup function that unsubscribes when called.

Signature​

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

type GraniteEvent = {
  backEvent: {
    onEvent: () => void;
    onError?: (error: Error) => void;
    options?: void;
  };
  homeEvent: {
    onEvent: () => void;
    onError?: (error: Error) => void;
    options?: void;
  };
};

declare const graniteEvent: {
  addEventListener: <K extends keyof GraniteEvent>(
    event: K,
    handlers: {
      onEvent: GraniteEvent[K]['onEvent'];
      onError?: GraniteEvent[K]['onError'];
      options?: GraniteEvent[K]['options'];
    }
  ) => () => void;
};

Parameters​

NameTypeRequiredDescription
event'backEvent' | 'homeEvent'✓Event name to subscribe.
handlers.onEvent() => void✓Handler called when the event fires. No payload.
handlers.onError(error: Error) => void—Handler called on error.
handlers.optionsvoid—Not used currently.

Event types​

EventFires when
backEventThe hardware or software back button is pressed
homeEventThe home button is pressed

Returns​

  • () => void — cleanup function that unsubscribes. Use as the useEffect return value.
caution

Subscribing to backEvent suppresses the default back navigation. You must implement your own navigation logic (e.g. history.back() or navigate(-1)) inside the onEvent handler.

Permission​

No permission required — graniteEvent.addEventListener is not bound to a PermissionName.

Examples​

Minimal — backEvent​

import { graniteEvent } from '@apps-in-toss/web-framework';
import { useEffect } from 'react';
import { useNavigate } from 'react-router-dom';

function Page() {
  const navigate = useNavigate();

  useEffect(() => {
    const cleanup = graniteEvent.addEventListener('backEvent', {
      onEvent: () => {
        navigate(-1);
      },
    });
    return cleanup;
  }, [navigate]);

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

Minimal — homeEvent​

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

function Page() {
  useEffect(() => {
    const cleanup = graniteEvent.addEventListener('homeEvent', {
      onEvent: () => {
        // e.g. save in-progress work
        console.log('Home button pressed.');
      },
    });
    return cleanup;
  }, []);

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

Realistic — confirm dialog before back navigation​

import { graniteEvent } from '@apps-in-toss/web-framework';
import { useEffect, useState } from 'react';
import { useNavigate } from 'react-router-dom';

function EditPage() {
  const navigate = useNavigate();
  const [isDirty, setIsDirty] = useState(false);

  useEffect(() => {
    const cleanup = graniteEvent.addEventListener('backEvent', {
      onEvent: () => {
        if (isDirty) {
          const confirmed = window.confirm('You have unsaved changes. Leave anyway?');
          if (!confirmed) return;
        }
        navigate(-1);
      },
    });
    return cleanup;
  }, [isDirty, navigate]);

  return (
    <form onChange={() => setIsDirty(true)}>
      {/* edit form */}
    </form>
  );
}

Try it live​

Subscribe to backEvent and homeEvent directly on the Events page in sdk-example.

Open in sdk-example

External references​