> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encorekit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger components

> Small Encore entries you place in your own screens that open the reward sheet, with looks Encore changes and tests without an app update.

A trigger component is a small Encore entry that sits inside one of your own screens, in the normal flow of your layout. When the user taps it, it opens the reward sheet for its placement: the same sheet `show()` presents, with the same premium brand offers, each one a real perk a brand funds to acquire customers.

Instead of deciding in code when to interrupt the user with the sheet, you place an entry where the reward makes sense and let the user open it when they choose to. You add it with one line and a placement ID. Encore decides how it looks.

<Info>
  **Requires SDK 2.4.0+** on every platform. See [Minimum SDK versions](#minimum-sdk-versions).
</Info>

## Minimum SDK versions

Trigger components first shipped in 2.4.0 of each SDK:

| Platform | Package | Minimum |
| - | - | - |
| iOS | `EncoreKit` ([install](/publishers/ios/quickstart/install)) | 2.4.0 |
| Android | `com.encorekit:encore` ([install](/publishers/android/quickstart/install)) | 2.4.0 |
| React Native | `@encorekit/react-native` ([install](/publishers/react-native/quickstart/install)) | 2.4.0 |
| Flutter | `encore_flutter` ([install](/publishers/flutter/quickstart/install)) | 2.4.0 |
| Web | `@encorekit/web-sdk` ([install](/publishers/web/quickstart/install)) | 2.4.0 |

The React Native and Flutter 2.4.0 packages bring the native 2.4.0 SDKs with them.

## The two trigger components

| Trigger component | What it is | Where it goes |
| - | - | - |
| [Gifts Button](/publishers/triggers/gifts-button) | A "you have a gift" entry: a card, an animated gift box, a thank you banner, or a compact pill. | A reward moment, such as the screen after a finished streak, in place of your own `show()` call |
| [Claim Reminder](/publishers/triggers/claim-reminder) | A card that reminds the user of an offer they claimed but haven't finished, with a countdown | A screen users return to on their own, such as your home screen |

Start with the [quickstart](/publishers/triggers/quickstart): it adds both in a few lines on iOS, Android, React Native, Flutter, and the web.

Prefer to draw the entry in your own style? [Build your own button](/publishers/triggers/custom-ui): Encore still decides what it shows, counts its views and taps, and opens the reward sheet.

## Looks come from Encore

Each trigger component's look (its layout, copy, colors, and height) is served by Encore, not built into your app. Encore draws it with the same engine that draws the reward sheet. That means:

* **No app update to change a look.** Encore can switch the Gifts Button from the card to the banner, or reword the Claim Reminder, for every user on a version that supports trigger components.
* **Encore can test looks.** Encore picks each trigger component's look, and can run an experiment comparing looks across your users. See [Experiments and looks](/publishers/triggers/experiments).
* **Copy arrives in the user's language.** See [Localization](/publishers/concepts/localization).

Your code never builds the entry's views. You place it and give it a placement. If you like, you also give it your own [text](#your-text) and [colors](#colors).

## Your text

Write the entry's words yourself with `headline`, `subheadline` and `cta`, the same names the reward sheet uses. Anything you leave out, or pass blank, shows the look's own copy, so you can set just the line you care about:

<CodeGroup>
  ```swift iOS theme={null}
  GiftsButton(placement: "streak")
      .headline("You kept your streak!")
      .subheadline("A gift from us, on the house")
      .cta("Open")
  ```

  ```kotlin Android theme={null}
  GiftsButton(
      placement = "streak",
      headline = "You kept your streak!",
      subheadline = "A gift from us, on the house",
      cta = "Open",
  )
  ```

  ```tsx React Native theme={null}
  <EncoreGiftsButton
    placement="streak"
    headline="You kept your streak!"
    subheadline="A gift from us, on the house"
    cta="Open"
  />
  ```

  ```dart Flutter theme={null}
  EncoreGiftsButton(
    placement: 'streak',
    headline: 'You kept your streak!',
    subheadline: 'A gift from us, on the house',
    cta: 'Open',
  )
  ```

  ```javascript Web SDK theme={null}
  Encore.triggers.giftsButton.mount(element, {
    placement: 'streak',
    headline: 'You kept your streak!',
    subheadline: 'A gift from us, on the house',
    cta: 'Open',
  });
  ```

  ```tsx Web SDK (React) theme={null}
  <GiftsButton
    placement="streak"
    headline="You kept your streak!"
    subheadline="A gift from us, on the house"
    cta="Open"
  />
  ```
</CodeGroup>

Claim Reminder takes the same three. On UIKit and Android Views, set the `headline`, `subheadline` and `cta` properties.

| Option | What it replaces |
| - | - |
| `headline` | The entry's main line |
| `subheadline` | The line under it |
| `cta` | The button's label |

How your text is shown:

* **Each look has its own default.** The copy you fall back to belongs to the look Encore serves, in the user's language. If Encore tests two looks, each falls back to its own words.
* **A look shows only the lines it has.** Your `cta` appears on looks that draw a button, and your `subheadline` on looks that draw a second line. No Claim Reminder look draws a subheadline today. A look with no place for a line keeps its own copy there.
* **Your text is shown as you pass it.** Encore doesn't translate it, so pass the user's language yourself if your app has more than one.
* **One line each, up to 120 characters.** Line breaks and invisible control characters are removed. Text with nothing visible left counts as blank.
* **The thanks look keeps Encore's words.** After a completion, the thanks look shows its own copy even when you pass text.
* **Screen readers keep the brand.** When your headline replaces a Claim Reminder's title, VoiceOver and TalkBack still read the advertiser's name.

## How it relates to the reward sheet

A trigger component is a way in to the reward sheet, not a second sheet:

* It shows only when the reward sheet it opens has offers for this user at this placement. It checks first, so a tap never opens an empty sheet.
* A tap opens that sheet exactly as `show()` would, with the offers it already checked.
* `publisherReward` and `onResult` work on that sheet as they do for `show()`. See [Pass your prize and read the result](/publishers/triggers/gifts-button#pass-your-prize-and-read-the-result).
* When the sheet closes, the entry checks again. It stays while offers remain and hides when none are left.

## What you can count on

These hold for every trigger component on every platform.

### It takes no space when there's nothing to show

A trigger component is zero height, and never shows an empty or broken entry, until it has something to show. Design every screen that holds one so it looks right both with and without it. [Troubleshooting](/publishers/triggers/troubleshooting#it-isnt-showing) lists every reason it can be empty.

### It never crashes your app

A trigger component never throws into your code. A network error, an unknown ID, or a look the SDK can't draw all end the same way: it renders nothing. A look that uses something your SDK version can't draw is never drawn partly or wrongly; the entry stays empty instead.

### It sizes itself

Its height comes from the look Encore serves, and it reports that height to your layout. Give it the width of your content and leave the height to the trigger component: put it in a stack, column, or list, and use `wrap_content` on Android Views. See [Heights](#heights) and [Width and alignment](#width-and-alignment).

### Its text follows the user's text size

The entry's text grows with the user's larger text setting, up to a limit set by the look, so the entry keeps its height. A long line shrinks to fit before it's cut off.

### It keeps itself current

It checks again when your app returns to the foreground and when the sheet it opened closes, and hides when what it showed no longer applies. It reloads when you call `identify()`, `reset()`, or `setLanguage()`, so a new user never sees the previous user's entry.

### Dismissals stay on the device

When a look lets the user dismiss the entry (the Claim Reminder's ×), the dismissal is stored on that device only. It hides that item on every screen showing the same trigger component. Nothing is sent to your server or changed on the user's account.

## Heights

These are the heights Encore serves today, in points on iOS, `dp` on Android, and CSS pixels on the web. React Native and Flutter take the iOS or Android value of the device. They're set by the look, so Encore can change them without an app update.

| Trigger component | Look | Height |
| - | - | - |
| Gifts Button | `card` | 76 |
| Gifts Button | `banner` | 88 |
| Gifts Button | `pulse` | 112 |
| Gifts Button | `pill` | 48 |
| Gifts Button | `offerMarquee`, `offerColumns`, `giftCard` and `stillWaiting` | 76 |
| Claim Reminder | `featured` | 85 |
| Claim Reminder | Every other look | 76 |

Looks in one experiment can have different heights, so a Gifts Button can change height between users. Leave the height flexible.

## Colors

Each trigger component reads these fields from the `appearance` you pass. That `appearance` styles only the trigger component, never the sheet it opens: set the sheet's look where you style your sheets, as you do when you present the sheet yourself.

| Field | What it colors | When you leave it out |
| - | - | - |
| `backgroundColor` | The entry's surface | The color order below |
| `textColor` | Titles and the countdown | The color order below |
| `accentColor` | Buttons, progress, and highlights | The color order below |
| `secondaryTextColor` | Subtitles, the countdown's units, and the close button | Your text color, faded by the look |
| `trackColor` | The unfilled part of a progress bar | Your text color, faded by the look |
| `onAccentColor` | Text and icons drawn on the accent | Black or white, whichever reads on the accent. Some looks draw button text in the entry's background color when that reads too |
| `backgroundEndColor` | The second color of a look's background gradient, such as the featured Claim Reminder's | Your background color, so the entry is solid |

For each color on its own, the first one set wins:

1. **Your `appearance`.**
2. **Your app's theme in the Encore portal.** Today this is the accent color you saved for the app.
3. **The look's own colors**, set by Encore.
4. **The built-in default**: a dark surface with a gold accent.

A color you set is drawn exactly as you set it. A look can fade its secondary text or its track, but only when you haven't set that color yourself.

Your `textColor` applies on its own, with or without a `backgroundColor`. When a background is set without a text color at the same step, the text is black or white, whichever reads on that background. Hex formats are `#RGB`, `#RRGGBB`, and `#RRGGBBAA`. A value that isn't a hex color is ignored, and the next step in the order applies. On the web, the reward sheet's other `AppearanceConfig` fields (`headline`, `claimButton`, and the rest) don't apply to the entry. To change the entry's words, use [`headline`, `subheadline` and `cta`](#your-text).

### Light and dark

`colorScheme` sets the look's mode: `light`, `dark`, or `system`, which follows the device. Leave it out and the entry follows the mode you saved for your app in the Encore portal, where `auto` follows the device. With neither set, the entry is dark.

In light mode, the order is your `appearance`, then your app's portal theme, then the look's light colors, then a light default: a white surface with dark text and a gold accent. A look's dark colors never apply in light mode.

## Icon

The `icon` option picks the icon the look draws. It goes on the trigger component itself, next to `placement`, not inside `appearance`:

* `gift`, the default: Encore's gift.
* `appIcon`: your app's store icon, from your app's settings in the Encore portal. When your app has no store icon, the look draws the gift.
* `none`: no icon.

Looks that show the advertiser's logo keep it whatever you set here.

## Width and alignment

A trigger component is never wider than its look. Encore sets that width for each look. In a container narrower than the look, such as a phone screen, it fills the container. In a wider one, such as a large screen or a desktop page, it keeps the look's width and sits where `alignment` puts it:

* `center`, the default.
* `leading`: the start of the line in your app's writing direction (left in English, right in Arabic).
* `trailing`: the end of the line.

`alignment` goes on the trigger component, next to `placement`. Gifts Button, Claim Reminder and the trigger host all take it:

<CodeGroup>
  ```swift iOS theme={null}
  ClaimReminder(placement: "home", alignment: .leading)
  ```

  ```kotlin Android theme={null}
  ClaimReminder(placement = "home", alignment = EncoreAlignment.LEADING)
  ```

  ```tsx React Native theme={null}
  import { EncoreClaimReminder, EncoreAlignment } from '@encorekit/react-native';

  <EncoreClaimReminder placement="home" alignment={EncoreAlignment.leading} />
  ```

  ```dart Flutter theme={null}
  EncoreClaimReminder(placement: 'home', alignment: EncoreAlignment.leading)
  ```

  ```javascript Web SDK theme={null}
  Encore.triggers.claimReminder.mount(element, { placement: 'home', alignment: 'leading' });
  ```

  ```tsx Web SDK (React) theme={null}
  <ClaimReminder placement="home" alignment="leading" />
  ```
</CodeGroup>

Changing `alignment` only moves the trigger component. It makes no new request and keeps the look already on screen. On Android Views set the `alignment` property, or `app:encoreAlignment` in XML; on the web call `setAlignment()` on the handle `mount()` returns.

## Analytics

Every trigger component reports its own impressions, taps, and dismissals to Encore's analytics. You don't send or handle any events.

## Related

* [Quickstart](/publishers/triggers/quickstart): add both trigger components.
* [Gifts Button](/publishers/triggers/gifts-button) and [Claim Reminder](/publishers/triggers/claim-reminder).
* [Build your own button](/publishers/triggers/custom-ui): draw the entry yourself; Encore still decides what it shows and opens the sheet.
* [Experiments and looks](/publishers/triggers/experiments): how Encore picks and tests looks.
* [Troubleshooting](/publishers/triggers/troubleshooting): when a trigger component isn't showing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.