Mastering apex.region().refresh() in Modern APEX

For years, refreshing an APEX region was… messy.

You probably did this:

JavaScript

$("#myRegion").trigger("apexrefresh");

And hoped for the best. Sometimes it worked. Sometimes it jumped to the top. Sometimes pagination resets. Users lost their place, got annoyed, and sent you a ticket. Or sometimes just use a plugin that keeps the scroll position on refresh.

Let’s be honest: That wasn’t a refresh strategy — it was guesswork, and when the plugin developer doesn't update it for the new versions, it become had to maintain.

I’ve seen this kind of "solution" in a couple of legacy APEX apps I recently worked on. Usually, it’s heavy lines of jQuery that try to "stash" the scroll position to preserve the state in sessionStorage before the refresh and "pop" it back after.

I extracted a bit of the snippet like this :

JavaScript

var lastScroll = $("#my_report .a-IRR-content").scrollTop(); 
$("#my_report").trigger("apexrefresh");
$("#my_report").on("apexafterrefresh", function() {
    $("#my_report .a-IRR-content").scrollTop(lastScroll);
});
//store state in a sessionStorage
...

Why this was a nightmare:

1. It relied on internal CSS classes (.a-IRR-content) that Oracle could change tomorrow.

2. It was a race condition. If the network lagged, the scroll "pop" happened too late.

3. It still didn't fix the fact that apexrefresh often booted the user back to Page 1.

The Shift: apex.region().refresh() Is Not Just a Replacement

Since APEX 24.2, it is now supported natively via the JS API or Dynamic Actions

JavaScript

var region = apex.region("my_report");
region.refresh();

At first glance, this looks like a cleaner version of the old way.

It’s not.It’s a contract between your code and the region.

What “Refresh” Actually Means Now

When you call region.refresh();, you’re not just reloading UI.

You’re telling APEX:“Re-fetch data, re-render correctly, and respect the region’s behaviour.”

And that behaviour depends on the region type.

That’s important—because APEX is now in control, not your hacky workaround.

The Feature Most People Miss: pKeepPagination

region.refresh(true);

That true is not a minor flag. It’s the "Don't Annoy My User" switch.

What it does:

• Keeps pagination (e.g., page 3 stays page 3)

• Preserves scroll position (natively, without hacky jQuery)

• Maintains user context

Under the Hood

“The refresh callback can and should return a Promise… Whether it does return one depends on the region or plug-in.”

The API signature shows {Promise} But internally it supports legacy regions, which means: If the region implements the region interface, refresh() may return a Promise, but if it fails, then it falls back to the legacy apexrefresh event, it returned undefined When I did some tests of writing this article. Maybe in the future this will be accessible.

var region = apex.region("staticId");

var result = region.refresh(true);   // using boolean parameter

console.log("Returned value:", result);

if (result && typeof result.then === "function") {

    console.log("This region supports Promise");

    result.then(function () {
        console.log("Promise resolved: refresh completed");
    });

} else {

    console.log("Region fell back to legacy apexrefresh event");

    apex.jQuery("#staticId").one("apexafterrefresh", function () {
        console.log("Refresh completed via event");
    });

}

typeof result.then ==="function" detects Promise or Promise-like objects

This is a massive upgrade. Before, you’d fire an event and just pray it finished. Now? It’s deterministic, chainable, and predictable.

Practical Pattern You Should Start Using

If your refresh is custom user-triggered, "Execute JavaScript" with this :

function Refreshreport(staticId) {
  const region = apex.region(staticId);
  if (region) {
    // Return the promise so the caller can chain off it
    return region.refresh(true); 
  }
}

In Dynamic Actions

You can use it in dynamic actions by flipping the toggle ON/OFF to Keep current pagination and scroll on refresh. I find this really useful when its baked into the product.

---

The Real Takeaway

apex.region().refresh() isn’t about fetching data. It’s about respecting the user’s state. If you’re still maintaining a local written code, you’re building technical debt. You’re working against the framework instead of with it.Always think built-in first.