Element Selector

The element sub-selector matches the element a file belongs to. It is the element key of an entity selector:

{ element: { /* element sub-selector */ } }

All values are micromatch pattern(s) unless noted. All conditions inside the selector are combined with AND; arrays act as OR.

Properties

• type — Matches the element's first type (types[0]). With single-type elements (the default), this is the only type, so type is all you need. (<string | string[] | null>)
• types — Matches against the element's type array. Accepts a micromatch pattern (matches if any type matches) or an array query object for richer constraints such as allOf, noneOf, and hasLength. (<string | string[] | null | ArrayQuery>)
• path — Matches the element path. (<string | string[] | null>)
• fileInternalPath — Matches the path of the file within its element (for example index.js). It will vary depending on the file that has been analyzed to get the element's information. (<string | string[] | null>)
• captured — Match captured values. (<object | object[] | null>)
• parent — Match the element's first parent. parent always targets only parents[0] (the nearest enclosing element). (<object | object[] | null>)
• parents — Array query over the full ancestor chain. parents[0] is the closest parent; the last element is the outermost ancestor. The full parents array is always available in templates (e.g. {{ element.parents.[0].types.[0] }}). (<ArrayQuery<ParentSelector>>)
• isIgnored — Whether the element is ignored. (<boolean>)
• isUnknown — Whether the file matches no element descriptor. (<boolean>)

// Match all helper elements
{ element: { type: "helper" } }

// Match components in a specific path
{ element: { type: "component", path: "**/components/atoms/**" } }

// Match elements with captured family "data"
{ element: { captured: { family: "data" } } }

// Match elements without any of types "deprecated" or "legacy"
{ element: { types: { noneOf: ["deprecated", "legacy"] } } }

// Match the entry file of any element
{ element: { fileInternalPath: "index.js" } }

// Match files that belong to no known element
{ element: { isUnknown: true } }

// Match element parents that are modules or have captured family "data"
{ element: { parents: { anyOf: [{ type: "module" }, { captured: { family: "data" } }] } } }

Info

All selector properties are optional. You can match on a single property, or combine several to target a more specific case. Remember that combined properties use AND logic — every one you specify must match.

Matching by type

A file can belong to more than one element type at the same path level. When multi-type elements are enabled (boundaries/elements-single-match: false), the runtime description carries every matching type in a types array. By default the plugin keeps a single type for backward compatibility, so an element's types array usually holds a single type.

The type selector property matches the element's first type — types[0]:

// Matches when the FIRST type is "component"
{ element: { type: "component" } }

The types selector property matches against the whole array — it matches if the pattern matches any of the element's types:

// Matches when ANY type is "component"
{ element: { types: "component" } }

Single-type vs multi-type elements

With single-type elements (the default), each element has exactly one type, so type and types behave the same. When multi-type elements are enabled, type still matches only the first type in the array, while types matches any type the element carries. See boundaries/elements-single-match for details.

Parent matching

Elements form a hierarchy: each element can be nested inside one or more enclosing elements. Two properties give you access to this ancestor chain: parents for full array query access, and parent as a shortcut for the common case of matching only the nearest ancestor.

Parent selector fields

Both parents and parent work with parent selector objects. A parent selector supports these fields:

• type — Matches the parent's first type (types[0]). (<string | string[] | null>)
• types — Matches against the parent's type array. Accepts a micromatch pattern (matches if any type matches) or an array query object for richer constraints such as allOf or hasLength. (<string | string[] | null | ArrayQuery>)
• path — Matches the parent element path. (<string | string[] | null>)
• captured — Matches the parent's captured values. (<object | object[] | null>)

parents — array query over the ancestor chain

parents accepts an array query object that matches against the full ancestor list. parents[0] is the closest parent (the immediately enclosing element); the last entry is the outermost ancestor.

// Top-level element (no parents)
{ element: { parents: { hasLength: 0 } } }

// Closest parent is a module
{ element: { parents: { atIndex: { index: 0, matches: { type: "module" } } } } }

// Outermost ancestor is an app
{ element: { parents: { atIndex: { index: -1, matches: { type: "app" } } } } }

// Closest parent is a module OR an app
{ element: { parents: { atIndex: { index: 0, matches: [{ type: "module" }, { type: "app" }] } } } }

// At least one ancestor is a module
{ element: { parents: { anyOf: [{ type: "module" }] } } }

// No ancestor is deprecated
{ element: { parents: { noneOf: [{ type: "deprecated" }] } } }

// Ancestor chain has exactly two levels in this order (closest first)
{ element: { parents: { equalsTo: [{ type: "module" }, { type: "app" }] } } }

// Closest parent has BOTH "module" AND "lazy" types
{ element: { parents: { atIndex: { index: 0, matches: { types: { allOf: ["module", "lazy"] } } } } } }

parent — shortcut for the closest parent

parent is a convenience that targets only parents[0] (the nearest enclosing element). It accepts a single parent selector object, an array of objects (OR), or null to match top-level elements with no parents.

// Closest parent is a module
{ element: { parent: { type: "module" } } }

// Top-level element (equivalent to parents: { hasLength: 0 })
{ element: { parent: null } }

Note

parent and parents can be used in the same selector — they are AND-combined, as any other properties in the element selector.

Deprecated element selector properties

The deprecated category, origin, elementPath, internalPath and filePath properties still work. Their replacements are on the Legacy Selectors page.

Next Steps

• Selectors — the entity/dependency model, array queries, captured values, and templating.
• File selector — match files by category.
• Module selector — match external and core module imports.
• Elements — define element descriptors and read the element description properties.
• Legacy Selectors — string/tuple formats and deprecated element properties.