Koru Countdown Bar

Urgency bar with fixed-date, evergreen, or daily countdowns — configurable without code.

Koru Countdown Bar is an urgency bar with a live countdown. Use it to support campaigns, limited-time offers, and recurring daily promotions.

All content — message, timer, colors, and button — is configured from Koru. You only add the integration code or install the VTEX app once.

You need a Website ID required and App ID required. Both are available in Koru under the app's Copy Code action / Integration Info section.

Installation

Choose the tab that matches your store. For VTEX IO, install the app; for any other platform, use the integration code.

The widget is installed as a Store Theme app and rendered with the countdown-bar block. Koru controls its content; the theme only contains the integration identifiers.

Add the app as a theme dependency

In your theme's manifest.json:

"dependencies": {
  "{vendor}.koru-countdown-bar": "0.x"
}

Replace {vendor} with the VTEX publisher account. Koru will provide the complete published App ID.

Declare the block where it should render

Declare countdown-bar in the corresponding theme block — header, footer, product page, or another template — with the Koru identifiers:

"countdown-bar": {
  "props": {
    "websiteId": "YOUR-WEBSITE-ID",
    "appId": "YOUR-APP-ID"
  }
}

Then add it as a child of the block where it should appear. For example, at the top of the header:

"header-layout.desktop": {
  "children": [
    "countdown-bar",
    "header-row#1-desktop",
    "header-row#2-desktop"
  ]
}

Use a `#id` for multiple instances

If the bar must appear in more than one place — for example, in the header and product page — declare each instance with its own #id and blockClass:

"countdown-bar#pdp": {
  "props": {
    "websiteId": "YOUR-WEBSITE-ID",
    "appId": "YOUR-APP-ID",
    "blockClass": "koru-pdp"
  }
}

That blockClass generates the countdownBar--koru-pdp handle used by CSS.

Koru stores one position per app. To render multiple simultaneous locations, select inline and control each instance through its blockClass.

Optionally adjust its shape with CSS

The bar inherits store colors and typography automatically. Shape-related properties such as radius, width, and sticky behavior belong in the theme CSS, targeting the instance handle. In the app override file (styles/css/<vendor>.koru-countdown-bar.css):

/* Compact rounded card for the product-page instance */
.countdownBar--koru-pdp {
  max-width: 350px;
  margin: 0 auto 20px;
  border-radius: 15px;
  overflow: hidden;
}
 
/* Header bar that stays at the top while scrolling */
.countdownBar--koru-header {
  position: sticky;
  top: 0;
  z-index: 1000;
}

Use direct handles (.countdownBar--…) in the app override file. Do not use :global() from another app's CSS file: the VTEX build rejects it.

Configuration and use

After installation, manage everything from Koru → Configure Apps → Koru Countdown Bar. No additional website changes are required.

Timer type

Choose how time is counted:

Type (`timer_type`)	Behavior	Fields used
Fixed date (`to-date`)	Counts down to an exact date and time. Use it for a one-time event or campaign.	`end_date`
Daily (`daily`)	Restarts every day and counts down to a fixed time.	`daily_end_time`
Evergreen (`evergreen`)	Counts a fixed duration from each visitor's first view and persists per visitor.	`duration_min`

Position

Position (`position`)	Behavior	Requires CSS?
`top-sticky`	Full-width bar fixed at the top on every page. It offsets the store header instead of covering it.	No
`bottom-sticky`	Full-width bar fixed at the bottom.	No
`inline`	Renders where the integration or VTEX block is placed.	Yes, when a custom shape is needed

Content and button

Field	Description
`message_text`	Main bar message, for example “Limited-time offer”.
`button_text`	Call-to-action label. Leave it empty to hide the button.
`button_link`	Destination URL for the button.
`show_days`	Shows or hides the Days unit.
`close_button`	Allows the visitor to close the bar; the choice is remembered for the session.
`font_size`	Message font size in pixels.

When the countdown ends

The on_finish setting controls what happens at zero:

Hide (`hide`)

The bar disappears. This is the default behavior.

Show a message (`message`)

The bar remains visible and displays finish_message.

Redirect (`redirect`)

The visitor is sent to finish_url.

Colors

Colors are intentionally optional. When they are not set in Koru, the bar inherits the store's background, text, and typography. To define an explicit palette, use bg_color, text_color, timer_bg, timer_text, button_bg_color, and button_text_color.

The button uses an urgency accent by default so it stands out. Override it with button_bg_color and button_text_color.