Hi, in this guide, you’ll learn how to use ArcAlphabetIndexer in HarmonyOS Next with ArkTS and ArkUI to build fast and circular-friendly navigation in your wearable apps.
📘 Introduction
Imagine you’re building a vocabulary or contacts app for a smartwatch. Users are swiping endlessly to find “Zebra” or “Tom.” Wouldn’t it be better if they could just tap a letter and jump there instantly?
That’s where ArcAlphabetIndexer comes in.
This component allows lightning-fast navigation through alphabetically sorted lists on circular screens, like HarmonyOS-powered smartwatches.
In this guide, you’ll learn how to:
- Build and sort a vocabulary list
- Create an index mapping for letters
- Connect an ArcList with ArcAlphabetIndexer
- Keep scrolling and selection in sync
- Optimize for circular UI/UX
This tutorial uses ArkTS and ArkUI, targets HarmonyOS Next (API version 18+).
🧩 What is ArcAlphabetIndexer?
ArcAlphabetIndexer is a specialized circular component that shows all letters (A–Z and #) around the edge of a round screen. Users can select a letter to instantly scroll a list to the matching section.
Key Features
- Optimized for circular UIs
- Alphabetical fast-jumping
- Synchronizes with list scroll position
- Works great with ArcList
⚙️ How to Implement ArcAlphabetIndexer Step by Step
🔤 1. Create the Word List
We start by defining a vocabulary list, where each item contains a word and its meaning.
interface Word {
text: string;
meaning: string;
}
private rawWords: Word[] = [
{ text: "Apple", meaning: "A red or green fruit" },
{ text: "Zebra", meaning: "A striped animal" },
{ text: "Ball", meaning: "A round object" },
...
];
🔠 2. Sort the List and Build Letter Index Map
Next, we sort the list alphabetically and build a map to track the first appearance of each letter.
sortAndGroupWords() {
this.sortedWords = this.rawWords.sort((a, b) => {
return a.text.localeCompare(b.text);
});
this.letterIndexMap.clear();
let currentLetter = '';
this.sortedWords.forEach((word, index) => {
const firstLetter = this.getFirstLetter(word.text);
if (firstLetter !== currentLetter) {
currentLetter = firstLetter;
this.letterIndexMap.set(firstLetter, index);
}
});
}
📜 3. Display Words Using ArcList and Track Scrolling
Use ArcList to display the words. We also detect the center item while scrolling, and update the selected letter in ArcAlphabetIndexer accordingly.
ArcList({ scroller: this.scrollerForList, initialIndex: 0, header: this.header }) {
ForEach(this.sortedWords, (word: Word, index: number) => {
ArcListItem() {
…
}
…
}
})
}
.onScrollIndex((firstIndex: number, lastIndex: number, centerIndex: number) => {
if (centerIndex < this.sortedWords.length) {
const currentWord = this.sortedWords[centerIndex];
const letter = this.getFirstLetter(currentWord.text);
const letterIndex = this.fullValue.indexOf(letter);
if (letterIndex !== -1) {
this.indexerIndex = letterIndex;
}
}
})
…
🔁 4. Enable Fast Navigation with ArcAlphabetIndexer
Here we wire up the ArcAlphabetIndexer to scroll the list to the correct item when a letter is selected.
ArcAlphabetIndexer({ arrayValue: this.fullValue, selected: 0 })
.onSelect((index: number) => {
this.indexerIndex = index;
const selectedLetter = this.fullValue[index];
if (selectedLetter !== '#' && this.letterIndexMap.has(selectedLetter)) {
const wordIndex = this.letterIndexMap.get(selectedLetter);
if (wordIndex !== undefined) {
this.scrollerForList.scrollToIndex(wordIndex);
}
}
})
…
📌 When the user taps “M”, the list instantly jumps to the first “M” word. Smooth and fast!
💻 5. Full Code Example
import {
LengthMetrics,
ColorMetrics,
ArcList,
ArcListItem,
ArcListAttribute,
ArcAlphabetIndexer,
ArcAlphabetIndexerAttribute,
ComponentContent
} from '@kit.ArkUI';
interface Word {
text: string;
meaning: string;
}
@Builder
function buildText() {
Column() {
Text('Word List')
.fontSize(26)
.fontWeight(FontWeight.Bold)
.fontColor(Color.White)
}.margin(6)
}
@Entry
@Component
struct Index {
private fullValue: string[] = [
'#', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N',
'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z'
];
private rawWords: Word[] = [
{ text: "Apple", meaning: "A red or green fruit" },
{ text: "Jump", meaning: "To leap up" },
{ text: "Zebra", meaning: "A striped animal" },
{ text: "Fan", meaning: "Cools the air" },
{ text: "X-ray", meaning: "Used to see bones" },
{ text: "Desk", meaning: "A table for work or study" },
{ text: "Orange", meaning: "A citrus fruit" },
{ text: "Train", meaning: "Runs on tracks" },
{ text: "Rain", meaning: "Water from sky" },
{ text: "Lion", meaning: "King of jungle" },
{ text: "Mouse", meaning: "A small rodent" },
{ text: "Kite", meaning: "Flies in the wind" },
{ text: "Unicorn", meaning: "Mythical horse" },
{ text: "Queen", meaning: "Female ruler" },
{ text: "Whale", meaning: "Large sea animal" },
{ text: "Car", meaning: "A vehicle with wheels" },
{ text: "Needle", meaning: "Used in sewing" },
{ text: "Egg", meaning: "Laid by birds" },
{ text: "Xylophone", meaning: "A musical instrument" },
{ text: "Guitar", meaning: "A musical instrument" },
{ text: "Ball", meaning: "A round object for playing" },
{ text: "Violin", meaning: "A string instrument" },
{ text: "Book", meaning: "Something you read" },
{ text: "Lamp", meaning: "Gives light" },
{ text: "Van", meaning: "A type of vehicle" },
{ text: "Yellow", meaning: "A bright color" },
{ text: "Dog", meaning: "A loyal pet animal" },
{ text: "Queen", meaning: "Female ruler" },
{ text: "Jelly", meaning: "A soft sweet food" },
{ text: "House", meaning: "A place to live" },
{ text: "Igloo", meaning: "A snow house" },
{ text: "Zoo", meaning: "Place for animals" },
{ text: "Ice", meaning: "Frozen water" },
{ text: "Moon", meaning: "Earth's satellite" },
{ text: "Pen", meaning: "Used to write" },
{ text: "Quilt", meaning: "A warm bedcover" },
{ text: "Cat", meaning: "A small pet animal" },
{ text: "Nest", meaning: "A bird's home" },
{ text: "Key", meaning: "Opens doors" },
{ text: "Ant", meaning: "A small insect" },
{ text: "Yacht", meaning: "A luxury boat" },
{ text: "Piano", meaning: "A musical instrument" },
{ text: "Elephant", meaning: "A large grey animal" },
{ text: "Game", meaning: "Something you play" },
{ text: "Hat", meaning: "Worn on the head" },
{ text: "Oven", meaning: "Used for baking" },
{ text: "Sun", meaning: "Shines in the sky" },
{ text: "Water", meaning: "Essential liquid" },
{ text: "Jacket", meaning: "Worn for warmth" },
{ text: "Robot", meaning: "A programmable machine" }
]
@State sortedWords: Word[] = [];
@State letterIndexMap: Map<string, number> = new Map();
private scrollerForList: Scroller = new Scroller();
@State indexerIndex: number = 0;
@State selectedWord: Word | null = null;
private watchSize: string = '466px';
private itemSize: number = 16;
context: UIContext = this.getUIContext()
header: ComponentContent<Object> = new ComponentContent(this.context, wrapBuilder(buildText));
aboutToAppear() {
this.sortAndGroupWords();
}
getFirstLetter(word: string): string {
return word.charAt(0).toUpperCase();
}
sortAndGroupWords() {
this.sortedWords = this.rawWords.sort((a, b) => {
return a.text.localeCompare(b.text);
});
this.letterIndexMap.clear();
let currentLetter = '';
this.sortedWords.forEach((word, index) => {
const firstLetter = this.getFirstLetter(word.text);
if (firstLetter !== currentLetter) {
currentLetter = firstLetter;
this.letterIndexMap.set(firstLetter, index);
}
});
}
build() {
Column() {
Row() {
Stack() {
ArcList({ scroller: this.scrollerForList, initialIndex: 0, header: this.header }) {
ForEach(this.sortedWords, (word: Word, index: number) => {
ArcListItem() {
Column({space: 6}) {
Text(word.text)
.fontSize(18)
.fontWeight(FontWeight.Bold)
.textAlign(TextAlign.Center)
.fontColor("#FF0B1F3B")
Text(word.meaning)
.fontSize(12)
.fontColor(Color.Gray)
.textAlign(TextAlign.Center)
.maxLines(2)
.textOverflow({ overflow: TextOverflow.Ellipsis })
.fontColor(Color.Gray)
}
.backgroundColor(Color.White)
.width('90%')
.height(50)
.padding(8)
.borderRadius(23)
.justifyContent(FlexAlign.Center)
.onClick(() => {
this.selectedWord = word;
})
}
})
}
.scrollBar(BarState.Off)
.onScrollIndex((firstIndex: number, lastIndex: number, centerIndex: number) => {
if (centerIndex < this.sortedWords.length) {
const currentWord = this.sortedWords[centerIndex];
const letter = this.getFirstLetter(currentWord.text);
const letterIndex = this.fullValue.indexOf(letter);
if (letterIndex !== -1) {
this.indexerIndex = letterIndex;
}
}
})
.borderWidth(1)
.width(this.watchSize)
.height(this.watchSize)
.borderRadius(this.watchSize)
.space(LengthMetrics.px(4))
ArcAlphabetIndexer({ arrayValue: this.fullValue, selected: 0 })
.autoCollapse(true)
.width(this.watchSize)
.height(this.watchSize)
.usePopup(false)
.selected(this.indexerIndex)
.onSelect((index: number) => {
this.indexerIndex = index;
const selectedLetter = this.fullValue[index];
if (selectedLetter !== '#' && this.letterIndexMap.has(selectedLetter)) {
const wordIndex = this.letterIndexMap.get(selectedLetter);
if (wordIndex !== undefined) {
this.scrollerForList.scrollToIndex(wordIndex);
}
}
})
.borderWidth(1)
.hitTestBehavior(HitTestMode.Transparent)
.selectedColor(ColorMetrics.resourceColor(0xFFFFFF))
.selectedBackgroundColor(ColorMetrics.resourceColor(0x1F71FF))
.color(ColorMetrics.resourceColor(0xFFFFFF))
.popupColor(ColorMetrics.resourceColor(0xFFFFFF))
.popupBackground(ColorMetrics.resourceColor(0xD8404040))
.itemSize(LengthMetrics.px(this.itemSize))
.selectedFont({
size: '11.0fp',
style: FontStyle.Normal,
weight: 500,
family: 'HarmonyOS Sans'
})
.font({
size: '11.0fp',
style: FontStyle.Normal,
weight: 500,
family: 'HarmonyOS Sans'
})
}
.width('100%')
.height('100%')
}
.width('100%')
.height('100%')
}
.width('100%')
.height('100%')
.linearGradient({
direction: GradientDirection.Bottom,
colors:
[
["#FF0B1F3B", 0.0],
["#FF00050A", 1],
]
})
}
}
🧠 Tips and Warnings
✅ Use short words to avoid layout overflow on round screens.
✅ Sort list alphabetically before using the indexer.
✅ Use ArcList and ArcAlphabetIndexer inside a Stack to align them properly.
⚠️ Avoid overcrowding the UI with too many elements.
⚠️ Works only on API 18+ and circular devices.
✅ Conclusion
ArcAlphabetIndexer gives your wearable apps a professional, responsive, and elegant navigation experience — just like scrolling through contacts or vocabulary with ease.
This component is lightweight but powerful, especially when combined with ArcList.
🚀 Try it in your next HarmonyOS Next wearable project and elevate your UX!
📚 References
For more information about ArcList, here is an article written by my teammate (Bilal Basboz) : ArcList
For more information about ArcAlphabetIndexer, please visit the link : ArcAlphabetIndexer
Top comments (0)