oxc-project/oxc · error · OxcDiagnostic

Missing "key" prop for element in iterator.

Error message

Missing "key" prop for element in iterator.

What it means

The iterator variant of react/jsx-key: a JSX element is produced inside an iterator callback without a 'key' prop. The rule detects calls whose callee name is one of TARGET_METHODS = ["flatMap", "from", "map"] (plus React.Children.toArray) and reports elements returned from their callbacks. It carries two labels — 'Iterator starts here.' on the iterator span and 'Element generated here.' on the element — plus a help link to the React docs on keeping list items in order with key.

Source

Thrown at crates/oxc_linter/src/rules/react/jsx_key.rs:35

use oxc_macros::declare_oxc_lint;
use oxc_span::{GetSpan, Span};

use crate::{
    AstNode,
    ast_util::is_node_within_call_argument,
    context::{ContextHost, LintContext},
    rule::{DefaultRuleConfig, Rule},
    utils::default_true,
};

const TARGET_METHODS: [&str; 3] = ["flatMap", "from", "map"];

fn missing_key_prop_for_element_in_array(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn(r#"Missing "key" prop for element in array."#).with_label(span)
}

fn missing_key_prop_for_element_in_iterator(iter_span: Span, el_span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn(r#"Missing "key" prop for element in iterator."#)
        .with_help(r#"Add a "key" prop to the element in the iterator (https://react.dev/learn/rendering-lists#keeping-list-items-in-order-with-key)."#)
        .with_labels([
            iter_span.label("Iterator starts here."),
            el_span.label("Element generated here."),
        ])
}

fn key_prop_must_be_placed_before_spread(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn(r#""key" prop must be placed before any `{...spread}`"#)
        .with_help("To avoid conflicting with React's new JSX transform: https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html")
        .with_label(span)
}

fn duplicate_key_prop(key_value: &str, span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn(format!("Duplicate key '{key_value}' found in JSX elements"))
        .with_help("Each child in a list should have a unique 'key' prop")
        .with_label(span)
}

View on GitHub (pinned to e1e7af627c)

Solutions

1. Add key={...} with a unique stable value to the element returned by the callback: items.map(x => <Row key={x.id}/>)
2. Use the item's stable id rather than the array index when order can change
3. When a fragment groups multiple elements per iteration, put the key on the <Fragment key={...}> shorthand, not on children
4. Keep every element generated by the iteration keyed, including elements inside conditionals within the callback

Example fix

// before
{items.map(x => <Row data={x}/>)}

// after
{items.map(x => <Row key={x.id} data={x}/>)}

npx oxlint -D react/jsx-key src/

When it happens

Trigger: items.map(x => <Row/>) or items.flatMap(x => [<Row/>, <Divider/>]) or Array.from(items, x => <Row x={x}/>) where the produced element lacks a key prop; also elements nested inside those callbacks (e.g. wrapped in unnecessary parens or conditionals) without keys.

Common situations: Rendering lists in components; refactoring for-loops into .map chains; forgetting keys when the callback body is a conditional or fragment; nested maps producing keyed outer elements but unkeyed inner ones.

Related errors

• Missing "key" prop for element in array.
• Duplicate key '{key_value}' found in JSX elements
• "key" prop must be placed before any `{...spread}`
• `button` elements must have an explicit `type` attribute.
• `button` elements must have a valid `type` attribute.

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/bf86cb2d33a2427a. Report an issue: GitHub.