DOMEvent

Used to track DOM events. Wraps a child component and triggers the specified event handler.
It is one of the event components returned as the first element of the createTracker tuple.


import { createTracker } from "@offlegacy/event-tracker";
 
const [Track] = createTracker({
  DOMEvents: {
    onFocus: (params, context) => {
      // Handle focus event
    },
  },
});
 
function App() {
  return (
    <Track.Provider initialContext={{}}>
      <Track.DOMEvent type="onFocus" params={{ ... }}>
        <input />
      </Track.DOMEvent>
    </Track.Provider>
  );
}

Reference

Props

Prop	Type	Description	Required
`type`	`DOMEventNames`	Event name (e.g., `"onClick"`, `"onFocus"`)	Yes
`enabled`	`boolean \| ((context: Context, params: EventParams) => boolean)`	Conditionally enable/disable tracking (default: `true`)	-
`debounce`	`DebounceConfig`	Debounce configuration to prevent rapid consecutive events	-
`throttle`	`ThrottleConfig`	Throttle configuration to limit event frequency	-
`schema`	`string`	Schema name for validating event parameters	-

Note: debounce and throttle are mutually exclusive and cannot be used together. A type error prevents invalid usage.

The type of the params prop differs depending on whether a schema is used.

With schema:

Prop	Type	Description
`params`	`SchemaParams \| (context: Context) => SchemaParams`	Schema-based parameters

Without schema:

Prop	Type	Description
`params`	`EventParams \| (context: Context) => EventParams`	Event parameters

`params` (Required)

With schema:

Type: SchemaParams | (context: Context) => SchemaParams
Description: Schema-based parameters.

Without schema:

Type: EventParams | (context: Context) => EventParams
Description: Standard event parameters.

`enabled`

Type: boolean | ((context: Context, params: EventParams) => boolean)
Description: Conditionally enable or disable event tracking (default: true).

`debounce`

Type: DebounceConfig
Description: Configure debouncing to avoid multiple rapid event triggers.

`throttle`

Type: ThrottleConfig
Description: Configure throttling to limit event frequency.

`schema`

When using schemas:

Type: string
Description: Schema name used to validate event parameters.

Examples

Custom Event Handler Name


function MyInput({ onInputFocus }: { onInputFocus?: () => void }) {
  return <input onFocus={onInputFocus} />;
}
 
function App() {
  return (
    <Track.Provider initialContext={{}}>
      <Track.DOMEvent type="onFocus" params={{ ... }} eventName="onInputFocus">
        <MyInput />
      </Track.DOMEvent>
    </Track.Provider>
  );
}

Using the eventName prop lets you specify a custom handler name, providing flexibility if the handler name differs from the DOM event name.

Conditional Event


<Track.DOMEvent type="onFocus" params={{ inputId: "email" }} enabled={(context) => context.trackingEnabled}>
  <input type="email" />
</Track.DOMEvent>

Debounced Event


<Track.DOMEvent
  type="onChange"
  params={{ inputId: "search" }}
  debounce={{ delay: 500, leading: false, trailing: true }}
>
  <input type="search" />
</Track.DOMEvent>

Throttled Event


<Track.DOMEvent
  type="onScroll"
  params={{ elementId: "main-content" }}
  throttle={{ delay: 100, leading: true, trailing: false }}
>
  <div>Scrollable Content</div>
</Track.DOMEvent>