scalpel@labs: ~/glossary/datalayer-push.mdx5 sections

What is a dataLayer push?

A dataLayer push is a call to `dataLayer.push(...)`. It appends one object to the array. Google Tag Manager watches for pushes, and a Custom Event trigger fires when a push carries a matching `event` value, such as `add_to_cart`.

extension: Scalpel Tagsupdated: 2026-08-14read_time: 2 min
less datalayer-push.mdx

Why it matters

Every tag you fire in GTM fires because of a push. Without pushes, GTM has nothing to react to. A push is how your site tells GTM "something happened": a page loaded, a button was clicked, a form was submitted, a product was viewed. GTM's entire job is to listen for these events and decide which tags should run in response.

How it works

A push is a single call to the array. Each call adds one object. That object typically has an event key (the event name) and any other data you want GTM to know about.

Here's the flow:

  1. Something happens on the page (user clicks, page loads, form submits).
  2. Your JavaScript calls dataLayer.push({event: 'event_name', ...data}).
  3. GTM's script intercepts this push and broadcasts it internally.
  4. GTM's triggers check: "Is this the event I'm listening for?"
  5. If there's a match, the tag fires. If not, nothing happens.

Important: pushes before the GTM script loads still count. GTM reads all entries already in the array when it initialises, so you can push events in the page <head> before GTM arrives. Scalpel Tags flags these replayed pushes so you know they fired before the hook attached.

One thing to avoid: do not replace the entire dataLayer array. If you do window.dataLayer = [...], you break GTM's internal hook. Always push into the existing array with .push().

What does not matter

You do not need to push an event key on every push. You can push data that only updates the dataLayer state without triggering a Custom Event. For example, you could push {user: {logged_in: true}} with no event. That updates the state, and GTM can read it on the next event that fires, but nothing triggers just from that push alone. This is useful for setting up context before a later push fires.

Also, the order of keys in the object does not matter. GTM reads all keys regardless of which one is first.

Code example

// Good: push with an event key
dataLayer.push({
  event: 'add_to_cart',
  product_name: 'Running Shoe',
  product_price: 79.99,
  quantity: 1
});

// Good: push without an event, just updates state
dataLayer.push({
  user_login_date: '2026-07-19'
});

// Bad: replacing the entire array breaks GTM
// Don't do this:
// dataLayer = [{event: 'page_view'}]; // Breaks the hook.

// Good: push to the existing array
dataLayer.push({event: 'page_view', page_path: '/'});

How Scalpel Tags shows it

Each push appears as a row in the dataLayer timeline on the panel. The timestamp shows when it fired. The event name shows in the first column (or "no event" if the push has no event key). Click the row to expand and see the full object. The diff view shows what that push added, changed, or removed from the accumulated state. The State view shows the entire dataLayer as it stands after that push.

Sources