Finding components

Three ways to find the components you want, mirroring the ways they're identified. All three are methods on your experience handle — and on any component — so there's nothing extra to import:

const experience = await connect()

experience.findByLocator('hero') // by the name you gave it in Flex
experience.findByTag('cml-video') // by component type
experience.findById('a1b2c3') // by internal id

Two things are true of all of them:

• They always return a ComponentSet — 0, 1, or many matches. There's no separate single-component return type; one match is a set of one. Narrow with .only() or .first() when you want the component itself.
• They query the page as it is right now. There's no waiting and no live updating: components that appear later aren't added to a set you already captured. Look them up again when you need them.

findByLocator(locator)

findByLocator(locator: string): ComponentSet

The one you'll use most. Finds every component carrying the name you assigned in Flex's SDK Locators inspector.

// react to a click on any element named "cta"
experience.findByLocator('cta').on('component.click', (event) => {
  console.log('clicked', event.target.cmlLocator)
})

Locators behave like CSS classes:

• Reuse a name to group elements. Three cards sharing the locator card are all returned by findByLocator('card'), and one call reaches all three.
• One element can carry several names, space-separated. An element named cta hero matches findByLocator('cta') and findByLocator('hero').
• Query one name at a time. A value containing a space never matches.

Because the locator is a name your team controls, it's the most stable way to target a component: restyling, resizing, and moving the element won't break it.

findByTag(tag)

findByTag(tag: string): ComponentSet

Finds every component of a given type. Useful for sweeping operations.

experience.findByTag('cml-video').media.pause() // pause every video

Common tags: cml-text, cml-video, cml-image, cml-rectangle, cml-oval, cml-polygon, cml-svg, cml-embed, cml-group, cml-section.

An invalid tag returns an empty set and logs a warning rather than throwing.

findById(id)

findById(id: string): ComponentSet

Finds the component with a given internal id. Ids are generated by Ceros rather than chosen by you, so reach for this only when you already have one in hand — from component.cmlId, say. Prefer findByLocator for anything you're writing by hand.

experience.findById('a1b2c3').only().componentType // 'cml-text'

Searching inside one component

A search is always scoped to the thing you call it on. Your experience handle covers the whole experience; calling the same method on a Component searches only that component's contents (and never matches the component itself):

const pricing = experience.findByLocator('pricing').only()

pricing.findByTag('cml-text') // only the text inside the pricing section

This is how you disambiguate a locator that's reused across sections — scope first, then find.

Which one to use

Method	Reach for it when
findByLocator	Almost always. You named the element in Flex and your script targets that name.
findByTag	You want every component of a kind — "pause all videos", "hide every embed".
findById	You already have an internal id from somewhere else. Rare.