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-type: 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-type 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

Deprecated

Several element selector properties — category, origin, elementPath, internalPath, filePath, and the parent-level elementPath — are kept for backward compatibility but are deprecated. They still work and are converted internally.

Use the modern replacements instead: the file sub-selector categories, the module sub-selector origin, element.path, and element.fileInternalPath. The full list, with migration tables, lives on the Legacy Element 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.