data-arcy Attributes

The data-arcy attribute is how you tell the ARCY assistant where things are in your UI. Add it to any element you want the assistant to be able to highlight, scroll to, or reference in its responses.

Basic usage

Add data-arcy with a stable, descriptive ID to any element:

<button data-arcy="invite-team-button">
  Invite team
</button>

<nav data-arcy="main-sidebar">
  ...
</nav>

<div data-arcy="billing-section">
  ...
</div>

The ID should describe what the element is, not where it appears on the page. Use short, lowercase, hyphen-separated strings.

How ARCY uses it

When the assistant highlights a feature or walks a user through a guided flow, it finds the relevant element on the page using these IDs. For example, a guided flow step might say:

{
  anchorId: "invite-team-button",
  message: "Click here to invite your first teammate."
}

The SDK resolves invite-team-button to the element that has data-arcy="invite-team-button" and highlights it with a visual indicator.

If the ID is not found on the current page, the SDK logs a warning in development:

[Arcy SDK] Element not found: "invite-team-button". Add data-arcy="invite-team-button" to the target element.

Naming conventions

Keep IDs stable across deploys. If you rename an ID, update any guided flows that reference it at the same time.

Good names:

• create-project-button
• team-members-table
• settings-billing-section
• sidebar-nav

Avoid:

• Generic names like button or section that could match multiple things
• Names tied to position like top-left-button or second-card
• Names that include implementation details like react-query-form-container

Where to add attributes

Add data-arcy to the elements your users actually interact with, and to the containers that visually represent important sections of your product.

Typical candidates:

• Primary action buttons (create, publish, invite, assign)
• Navigation items (sidebar links, tabs)
• Key feature sections (billing, settings, analytics panels)
• Empty states with call-to-action elements
• Forms and their submit buttons

You do not need to mark up every element. Focus on the ones you expect guided flows to reference and the ones the assistant is most likely to point users toward.

Register attributes in .arcy/routes/ YAML

After adding data-arcy attributes to elements, document them in the relevant .arcy/routes/[slug].yaml file under sections.elements. This is the assistant's reference map: it reads these files to know which elements are available and what they do.

route:
  path: /settings/billing
  label: Billing

sections:
  - id: billing
    label: Billing
    anchorId: billing-section
    elements:
      - anchorId: billing-plan-card
        label: Current plan
        type: div
        description: "Shows the current active subscription plan."
      - anchorId: upgrade-plan-button
        label: Upgrade plan
        type: button
        description: "Opens the plan upgrade flow."
      - anchorId: invite-member-button
        label: Invite member
        type: button
        description: "Opens the invite team member dialog."

Every data-arcy ID you add to your JSX should have a matching entry in a route YAML file. If an ID is missing, the assistant cannot reference it accurately. Run arcy push after updating.

arcy init and data-arcy

When you run arcy init, the CLI analyzes your codebase and adds data-arcy attributes to key elements automatically. Review the changes it makes before committing them. You can always add more attributes manually.