GiftFeed
gift-feedStreams live gift events with sender, item, quantity, and combo emphasis.
Usage
Basic usage
Controlled incoming gift event stream (events array append), the component automatically merges with the id combo and plays the entry animation.
const [events, setEvents] = useState<GiftEvent[]>([]);
//Add an event when receiving a gift; the same id is passed in again → combo is incremented
// setEvents((p) => [...p, { id: "g1", user: { name: "Local Rich Brother" }, gift: { name: "Rocket", icon: "🚀" }, combo }]);
<GiftFeed events={events} />Banner limit
max controls the number of banners on the screen at the same time (the oldest will be squeezed out if exceeded), only 1 is retained here.
<GiftFeed events={events} max={1} />Length of stay
duration Controls the dwell milliseconds after a single banner has no new combos. After shortening, the banner will dissipate faster.
<GiftFeed events={events} duration={2000} />When to use
Use GiftFeed in live or interactive experiences to show donation streak banners. Rapid gifts with the same id merge into combo ×N, reset the dismissal timer, and displace the oldest banner after the visible limit. This is a pointer-events:none effect layer above content. Use Result for general outcomes, Notification for ordinary messages, or pair it with FloatingReactions for floating likes.
Import
import { GiftFeed, applyGiftEvent } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| events* | GiftEvent[] | — | Append-only controlled stream. GiftEvent is {id, user:{name,avatar?}, gift:{name,icon?,color?}, combo?}; another event with the same id continues the streak. |
| max | number | 3 | Maximum simultaneously visible banners; the oldest is removed first. |
| duration | number | 4000 | Milliseconds a banner remains after its last event. |
| className | string | — | Container class name. |
applyGiftEvent is an exported pure function that merges an event into visible banners, increments or applies combo, and enforces max for isolated tests.
Example
const [events, setEvents] = useState<GiftEvent[]>([]);
function onGift(g: GiftEvent) {
setEvents((prev) => [...prev.slice(-30), g]);
}
<div className="relative h-72 w-80">
<GiftFeed events={events} max={3} duration={4000} className="w-full" />
</div>Usage guidelines
eventsis append-stream data. Only an identicalidcontinues a streak; give distinct gifts distinct ids to prevent accidental merging.- The caller maintains and increments
combo; without it, the component counts appearances. - Bound the events array, as in
.slice(-30), so a long-running stream does not grow indefinitely. - The banner's built-in Chinese verb is
"\u9001\u51fa", meaning “sent.” It renders between the user name and gift name; supply already-localized user and gift content for an English experience.
Related
Alert · Banner · Toast · Notification · ServiceMessage · Result