Designing for Circular Screens (Wearable) : How to Use ArkUI’s ArcButton in HarmonyOS Next

Read the original article：Designing for Circular Screens (Wearable) : How to Use ArkUI’s ArcButton in HarmonyOS Next

📘 Introduction

Hi, in this article, we’ll learn how to use the ArcButton component on HarmonyOS Next for wearable devices. ArcButton is a special button designed for circular screens like smartwatches. You’ll see how to add it, change its style, and try a few real examples.

Smartwatches usually have circular screens. So, buttons need to fit this shape. That’s why ArcButton is useful. It is made for wearable devices using HarmonyOS Next and ArkTS.

In this guide, we will:

Add an ArcButton to your app.
Try different styles and positions.
See how it looks on a watch screen.
Share some helpful tips.

Let’s get started!

🧩 What is ArcButton?

ArcButton is a circular UI button designed for wearable devices using HarmonyOS Next and ArkTS. It is made specifically for screens with a circular layout, like smartwatches.

Instead of placing buttons in flat rows, ArcButton allows them to sit naturally on the edge of a round display — either on the top or the bottom arc of the screen.

It works on API version 18 and above.

By using ArcButton, your app will feel more natural and comfortable on a watch screen.

⚙️ ArcButtonOptions: Customize Your ArcButton

ArcButton is flexible and supports many customizations through the ArcButtonOptions class. With these options, you can control not only how your button looks but also how it behaves.

Here’s a breakdown of the most useful properties:

position (ArcButtonPosition)
Sets where the button is placed: TOP_EDGE or BOTTOM_EDGE.
✅ Required | Default: BOTTOM_EDGE
styleMode (ArcButtonStyleMode)
Controls the button style. Options: EMPHASIZED_LIGHT, NORMAL, WARNING.
✅ Required | Default: EMPHASIZED_LIGHT
status (ArcButtonStatus)
Sets the button status. Usually just use NORMAL.
✅ Required | Default: NORMAL
label(ResourceStr)
The text shown inside the button.
✅ Required
backgroundBlurStyle (BlurStyle)
Adds blur effect to the background.
✅ Required | Default: NONE
backgroundColor (ColorMetrics)
Sets the button's background color.
✅ Required | Default: Color.Black
shadowColor(ColorMetrics)
Color of the button shadow.
✅ Required | Default: Color.Black
shadowEnabled (boolean)
Turns the shadow on or off.
✅ Required | Default: false
fontSize (LengthMetrics)
Controls the text size inside the button.
✅ Required | Default: 19fp
fontColor (ColorMetrics)
The normal text color.
✅ Required | Default: Color.White
pressedFontColor (ColorMetrics)
Text color when the button is pressed.
✅ Required | Default: Color.White
fontStyle (FontStyle)
The font style, like Normal or Italic.
✅ Required | Default: Normal
fontFamily (string or Resource)
Sets the font family used in the button text.
✅ Required | Example: "HarmonySans"
fontMargin (LocalizedMargin)
Controls padding around the text inside the button.
✅ Required | Default: { start: 24vp, top: 10vp, end: 24vp, bottom: 16vp }
onTouch (Callback)
Runs a function when the button is touched.
❌ Optional
onClick (Callback)
Runs a function when the button is clicked.
❌ Optional

📦 Import Required Modules

Before using ArcButton, import these modules:

import {
  ArcButton,
  ArcButtonOptions,
  ArcButtonStatus,
  ArcButtonStyleMode,
  ArcButtonPosition,
} from '@kit.ArkUI';

✏️ Example of ArcButton Usage

import {
  ArcSwiper,
  ArcSwiperAttribute,
  ArcSwiperController,
  ArcButton,
  ArcButtonOptions,
  ArcButtonPosition,
  ArcButtonStyleMode
} from '@kit.ArkUI'

@Entry
@Component
struct Index {
  private wearableSwiperController: ArcSwiperController = new ArcSwiperController()

  @Builder
  private arcButton(label: string, position: ArcButtonPosition, onClick: () => void) {
    ArcButton({
      options: new ArcButtonOptions({
        label,
        position,
        styleMode: ArcButtonStyleMode.EMPHASIZED_LIGHT,
        onClick
      })
    })
  }

  build() {
    Column() {
      Stack() {
        ArcSwiper(this.wearableSwiperController) {
          ForEach(ITEMS, (item: ItemInfo) => {
            Row() {
              Text(item.text)
                .fontSize(20)
                .fontColor(Color.Black)
            }
            .alignItems(VerticalAlign.Center)
            .justifyContent(FlexAlign.Center)
            .width('100%')
            .height('100%')
            .backgroundColor(item.bgColor)
          })
        }
        .vertical(true)
        .indicator(false)

        Column() {
          this.arcButton('Prev', ArcButtonPosition.TOP_EDGE, () => {
            this.wearableSwiperController.showPrevious();
          })

          Blank()

          this.arcButton('Next', ArcButtonPosition.BOTTOM_EDGE, () => {
            this.wearableSwiperController.showNext();
          })
        }
        .width('100%')
        .height('100%')
      }
    }
  }
}

export interface ItemInfo
{
  text: string;
  bgColor: Color
}

export const ITEMS: ItemInfo[] = [
  { text: 'This is a item-1', bgColor: Color.White },
  { text: 'This is a item-2', bgColor: Color.Orange },
  { text: 'This is a item-3', bgColor: Color.Yellow }
]

⚠️ Tips and Warnings

ArcButton works only on wearable devices.
Test buttons on a real or simulated circular screen.
Use short labels like “OK”, “Start”, “Back” for better fit.
Avoid placing too many buttons on one screen.
Always check API version (18+).

✅ Conclusion

ArcButton is a simple but powerful component for building watch-friendly UIs. It helps make your HarmonyOS Next wearable apps more user-friendly and good-looking.