Incoming Records Indicator

Demonstrates the useRecentlyAdded composable and the arc overlay for notifying users of newly arrived records.

How it works

useRecentlyAdded(records, keyField) returns a composable instance you pass to <DfGrid :recently-added="...">.

When you call addRecentlyAdded(pks, timeout?):

• Each pk is added to the recently-added list with a timestamp.
• The grid applies the state-adding CSS class to rows whose pk is in the list.
• If any pk maps to a row above the current viewport, a flash arc appears at the top of the body.
• If any pk maps to a row below the current viewport, a flash arc appears at the bottom.
• After timeout ms (default 250) each pk is automatically removed from the list.

The arc flashes at incomingArcMaxOpacity (default 1) on the first trigger and then fades linearly to zero over 800 ms. If triggered again within 1.5 s, each successive flash starts a further 15 % of incomingArcMaxOpacity lower than the one before, down to a floor of 0.15 × incomingArcMaxOpacity.

Row animation

Apply a CSS animation to .df-grid.card.state-adding. The example below scales the card open and follows with a brightness wink — neither a transform nor a filter changes the element's layout box, so the virtual scroll's pre-measured item sizes stay valid:

@keyframes df-row-scale-in {
  from { transform: scaleY(0); opacity: 0.3; }
  to   { transform: scaleY(1); opacity: 1;   }
}
@keyframes df-row-wink {
  0%, 100% { filter: brightness(1);   }
  50%      { filter: brightness(2.2); }
}
.df-grid.card.state-adding {
  transform-origin: center center;
  animation:
    df-row-scale-in 0.25s ease-out,
    df-row-wink     0.4s  0.25s ease-in-out both;
}

API

// records must be a Ref to the array the grid renders; wrap a reactive array with ref().
const recentlyAdded = useRecentlyAdded(records, 'id')

// Add pks. timeout (ms) controls how long the class stays on the row.
recentlyAdded.addRecentlyAdded([1, 2, 3], 600)

// Reactive: true while pk is in the list — use in rowClass or custom #item slot.
recentlyAdded.isPendingAdd(pk)

// Reactive (rAF-ticked): ms elapsed since pk was added, or null if not pending.
// Use when you need a JS animation keyed to exact elapsed time.
recentlyAdded.timeSinceAdded(pk)

// The row index range the grid currently shows; start is inclusive, end exclusive.
// The grid keeps it up to date and the arc detection compares new rows against it.
recentlyAdded.visibleRange.value

// Fire a flash yourself when your insertion logic knows more than the automatic detection.
recentlyAdded.triggerTopArc()
recentlyAdded.triggerBottomArc()

// True for 300 ms after each addRecentlyAdded call. While it is true the grid ignores click,
// double-click and long-press, so a row arriving under the finger cannot be mis-clicked.
// Scrolling, wheel, swipe and pinch are unaffected.
recentlyAdded.isAdding.value

Pass the instance to the grid:

<df-grid :recently-added="recentlyAdded" :incoming-arc-max-opacity="0.8" .../>

Arc slot override

Replace the default arc with your own content via named slots:

<df-grid :recently-added="recentlyAdded">
  <template #incoming-arc-top>
    <div class="my-custom-top-indicator">↑ New records above</div>
  </template>
  <template #incoming-arc-bottom>
    <div class="my-custom-bottom-indicator">↓ New records below</div>
  </template>
</df-grid>

Live demo

Scroll the grid to the middle, then press Add at top or Add at bottom to see the arc flash without row animation. Add in visible range inserts a record inside the viewport, where the row animation plays and no arc fires. Add random and Start auto-add mix both effects.

50 records

Id

 

Title

 

Artist

 

Year

 

Rating

 

1

Vogue

Ed Sheeran

2014

4

2

Back in Black

Black Sabbath

1986

4

3

Fade to Black

50 Cent

1978

4

4

Master of Puppets

The Weeknd

1965

2

5

R U Mine?

Mariah Carey

1991

1

6

Smells Like Teen Spirit

Willie Nelson

1959

2

7

Do I Wanna Know?

Nat King Cole

2011

4

8

About a Girl

Metallica

1994

3

9

Changes

Chicago

2003

2

10

Sanjam

Stevie Ray Vaughan

2016

2

11

Fade to Black

Ella Fitzgerald

1955

1

12

Thunderstruck

Fleetwood Mac

1959

1

13

Time

Eric Clapton

1989

4

14

Hotel California

Linkin Park

1976

3

15

Stairway to Heaven

Manca Špik

1989

5

16

Billie Jean

Nirvana

1986

4

17

Smells Like Teen Spirit

Big Foot Mama

2020

5

18

Time

The Who

1989

3

19

Come As You Are

Muddy Waters

1972

1

20

Enter Sandman

Adele

1961

4

21

Vertigo

Jay-Z

2004

2

22

Karma Police

B.B. King

1982

4

23

Whole Lotta Love

Jimi Hendrix

2008

2

24

Beautiful Day

Judas Priest

1974

4

25

Master of Puppets

Carlos Santana

2023

2

26

Fix You

Magnifico

1977

2

27

Whole Lotta Love

Manca Špik

1989

2

28

Beat It

Louis Armstrong

2022

3

29

Nothing Else Matters

Black Sabbath

2012

2

30

Kekec

Kanye West

2022

1

1

Vogue

Ed Sheeran

2014

4

2

Back in Black

Black Sabbath

1986

4

3

Fade to Black

50 Cent

1978

4

4

Master of Puppets

The Weeknd

1965

2

5

R U Mine?

Mariah Carey

1991

1

6

Smells Like Teen Spirit

Willie Nelson

1959

2

7

Do I Wanna Know?

Nat King Cole

2011

4

8

About a Girl

Metallica

1994

3

9

Changes

Chicago

2003

2

10

Sanjam

Stevie Ray Vaughan

2016

2

11

Fade to Black

Ella Fitzgerald

1955

1

12

Thunderstruck

Fleetwood Mac

1959

1

13

Time

Eric Clapton

1989

4

14

Hotel California

Linkin Park

1976

3

15

Stairway to Heaven

Manca Špik

1989

5

16

Billie Jean

Nirvana

1986

4

17

Smells Like Teen Spirit

Big Foot Mama

2020

5

18

Time

The Who

1989

3

19

Come As You Are

Muddy Waters

1972

1

20

Enter Sandman

Adele

1961

4

21

Vertigo

Jay-Z

2004

2

22

Karma Police

B.B. King

1982

4

23

Whole Lotta Love

Jimi Hendrix

2008

2

24

Beautiful Day

Judas Priest

1974

4

25

Master of Puppets

Carlos Santana

2023

2

26

Fix You

Magnifico

1977

2

27

Whole Lotta Love

Manca Špik

1989

2

28

Beat It

Louis Armstrong

2022

3

29

Nothing Else Matters

Black Sabbath

2012

2

30

Kekec

Kanye West

2022

1

31

Sweet Child O' Mine

Nina Simone

2000

5

32

Creep

Bob Dylan

1972

2

33

Changes

Chicago

2009

2

34

Sign O' the Times

Foo Fighters

1988

5

35

Knockin' on Heaven's Door

Metallica

1972

2

36

We Will Rock You

Johnny Cash

1984

5

37

Let's Dance

Van Halen

2003

2

38

Under Pressure

Adele

2013

5

39

Fix You

The Who

1995

1

40

Smells Like Teen Spirit

Coldplay

1967

1

41

Smooth Criminal

Manca Špik

2013

3

42

Thriller

Queen

2021

4

43

Papa Don't Preach

Garth Brooks

2013

5

44

Imagine

The Beatles

2019

5

45

Papa Don't Preach

Magnifico

1961

4

46

Little Red Corvette

Elvis Presley

2002

3

47

Come As You Are

Fleetwood Mac

2005

3

48

Sanjam

Black Sabbath

2002

5

49

505

Fleetwood Mac

2021

4

50

Thunderstruck

Bob Dylan

1963

3

1

Vogue

Ed Sheeran

2014

4

2

Back in Black

Black Sabbath

1986

4

3

Fade to Black

50 Cent

1978

4

4

Master of Puppets

The Weeknd

1965

2

5

R U Mine?

Mariah Carey

1991

1

6

Smells Like Teen Spirit

Willie Nelson

1959

2

7

Do I Wanna Know?

Nat King Cole

2011

4

8

About a Girl

Metallica

1994

3

9

Changes

Chicago

2003

2

10

Sanjam

Stevie Ray Vaughan

2016

2

11

Fade to Black

Ella Fitzgerald

1955

1

12

Thunderstruck

Fleetwood Mac

1959

1

13

Time

Eric Clapton

1989

4

14

Hotel California

Linkin Park

1976

3

15

Stairway to Heaven

Manca Špik

1989

5

16

Billie Jean

Nirvana

1986

4

17

Smells Like Teen Spirit

Big Foot Mama

2020

5

18

Time

The Who

1989

3

19

Come As You Are

Muddy Waters

1972

1

20

Enter Sandman

Adele

1961

4

21

Vertigo

Jay-Z

2004

2

22

Karma Police

B.B. King

1982

4

23

Whole Lotta Love

Jimi Hendrix

2008

2

24

Beautiful Day

Judas Priest

1974

4

25

Master of Puppets

Carlos Santana

2023

2

26

Fix You

Magnifico

1977

2

27

Whole Lotta Love

Manca Špik

1989

2

28

Beat It

Louis Armstrong

2022

3

29

Nothing Else Matters

Black Sabbath

2012

2

30

Kekec

Kanye West

2022

1