Component Indexing

Understanding the Need for Component Indexing

When building compound components with multiple instances of the same element type, we need to track the specific index of each item. This is crucial for features like:

• Determining the active slide in a carousel
• Managing selection in a list or tabs component
• Implementing keyboard navigation between related elements
• Tracking OTP input positions

Single vs. Multiple Component Instances

s Single instance components (like tooltips) don't typically need indexing:

<Tooltip.Root>
 <Tooltip.Trigger>
    Trigger
 </Tooltip.Trigger>
 <Tooltip.Content>
   Content
 </Tooltip.Content>
</Tooltip.Root>

Multiple instance components (like OTP inputs, radio groups, carousels) require proper indexing:

<RadioGroup.Root>
    <RadioGroup.Item /> {/* index 0 */}
    <RadioGroup.Item /> {/* index 1 */}
    <RadioGroup.Item /> {/* index 2 */}
</RadioGroup.Root>

Core Pattern

Indexing in QDS involves two key components:

1. Root Component: Maintains a counter in context
2. Item Components: Use useConstant to claim the next index

Implementation

Here's how to implement reliable indexing:

1. Root Component Setup

export const RadioGroupRoot = component$((props) => {
  // Initialize a counter that items will increment
  const currentIndex = 0;
  
  const context = {
    // ... other context properties
    currentIndex
  };

  useContextProvider(radioGroupContextId, context);

  return (
    <Render fallback="div" {...props}>
      <Slot />
    </Render>
  );
});

2. Item Component with useConstant

export const RadioGroupItem = component$((props) => {
  const context = useContext(radioGroupContextId);

  const index = useConstant(() => {
    // read the current index
    const currentIndex = context.currentIndex;

    // increment the index
    context.currentIndex++;

    // return the current index in the item instance
    return currentIndex;
  });

  return (
    <Render fallback="div" {...props}>
      <Slot />
    </Render>
  );
});

Key Takeaways

• Use useConstant for claiming sequential indexes in item components
• Maintain counters in context from the root component
• The pattern is reliable and works with any level of component composition
• Always increment after reading the current counter value