All rules

Sheath rule

native-key-hygiene

Repeated NativePHP elements and child components need unique, stable keys with the correct syntax.
Package
NativePHP
Category
Native
Default severity
warning by default
Auto-fix
Manual fix

#Why

NativePHP uses keys to preserve identity across updates. Missing, duplicated, constant, or position-based keys can attach state to the wrong item after a list changes order.

#Examples

#Bad

{{-- Every loop iteration receives the same literal key. --}}

@foreach ($articles as $article)

    <native:row native:key="article">

        <native:text>{{ $article->title }}</native:text>

    </native:row>

@endforeach

#Good

{{-- The bound record ID stays stable when list order changes. --}}

@foreach ($articles as $article)

    <native:row :native:key="$article->id">

        <native:text>{{ $article->title }}</native:text>

    </native:row>

@endforeach

Do not use $loop->index, $loop->iteration, or a for loop position as the identity.

#Native Elements And Components

Native elements use native:key. Registered child components use key:

<native:user-card :key="$user->id" />

The reversed spellings are reported. The outermost repeated native element and every repeated child component must have an identity on each known conditional render path.

Literal duplicate keys are checked within the same repeated-render scope. Mutually exclusive branches and separate keyed ancestor scopes do not conflict.

#Syntax

Key assignments need a value, quotes, and no whitespace around =. Opaque attribute maps and independently complex conditional paths are skipped when identity cannot be proven.

#Options

All NativePHP rules accept nativeViewPaths. The default is ['views/native/']. See Native View Detection for path configuration.

#See Also

Related rules cover component structure and repeated markup: