Kumu
  • Getting started
    • Welcome
    • Kumu 101
    • First steps
    • Quick tips
    • Webinars
  • Overview
    • Kumu's architecture
    • Accounts and workspaces
    • Kumu.io and Kumu Enterprise
    • Billing
    • User interfaces
      • Dashboard
      • Settings
      • Map editor
      • View editors
      • Quick Actions
    • Collaborating and sharing
    • Actions and permissions
    • Security
    • Advanced Editor hub
      • @settings reference
      • @controls reference
      • Color reference
      • Property reference
      • Selector reference
  • DISCIPLINES
    • SNA / Network Mapping
    • Systems mapping
    • Systems Practice workbook
  • Guides
    • Activity feed
    • Add-ons
      • Disqus
    • Bridge
    • Cluster
    • Controls
      • Cluster control
      • Color-legend control
      • Filter control
      • Focus control
      • Image control
      • Label control
      • Showcase control
      • SNA-dashboard control
      • Tagged-timeline control
      • Text Control
      • Title Control
      • View toggle control
    • Decorations
      • Direct decorations
      • Data-driven decorations
      • Flags
      • Icons
      • Images
      • Label templates
      • Popovers
    • Default view settings
    • Export
    • Fields
      • Computed fields
    • Filter
    • Focus
    • Forking
    • Grids & Guides
    • Import
      • Structure your data for Kumu
      • Excel / CSV
      • Google Sheets
      • JSON / Blueprints
    • Imported views
    • Layouts
      • Fixed
      • Force-directed
      • Remove overlap
      • Scatter
      • Snap-to
    • Legends
    • Licensing
    • Lightbox
    • Loops
    • Metrics
    • Two-factor authentication
    • Pro workspaces
      • Archiving projects
      • Discussions
    • Partial views
    • Presentations
    • Profiles
      • Markdown
    • Project admin
    • Selectors
    • Shapes
    • Share and embed maps
    • Shortcuts
    • Showcase
    • Slugs
    • Table
    • Templates
      • Geo template
    • URLs
    • Views
    • Widgets
  • About Kumu
    • What is Kumu?
    • How does it work?
    • Where can I get help?
  • Enterprise
    • About enterprise
    • Getting started with VMWare
    • Upgrading
    • Configuration
    • Creating user accounts
    • SSH Access
    • Single sign-on
    • Backing up enterprise data
    • Restoring enterprise data
    • Command line utilities
    • Changelog
  • Frequently Asked Questions
    • Does Kumu have a public API?
    • Does Kumu make use of AI?
    • How do I add annotations?
    • How do I add anchors to my map description?
    • How do I add arrows to my connections?
    • How do I add documents to profiles?
    • How do I add more than one element with the same label?
    • How do I add text dropdowns to my map overview?
    • How do I adjust arrow size?
    • How do I avoid duplicating data?
    • How do I change connection curvature?
    • How do I change font color?
    • How do I change font size?
    • How do I change the default for currency fields?
    • How do I change the length or strength of connections?
    • How do I change the order of control options?
    • How do I change the position of my element labels?
    • How do I cite Kumu?
    • How do I collapse duplicate connections?
    • How do I copy a map to another project?
    • How do I control label size while scaling element size?
    • How do I control text wrapping?
    • How do I convert a project from private to public?
    • How do I convert a project from public to private?
    • How do I create dynamic on/off toggles for my map?
    • How do I customize link text in popovers?
    • How do I customize the order of my legend?
    • How do I delete a project, map, or view?
    • How do I delete data from my project?
    • How do I downgrade my subscription?
    • How do I edit virtual elements?
    • How do I get rid of duplicates?
    • How do I hide elements without connections?
    • How do I hide images from the map but keep them in the profile?
    • How do I hide labels on my map?
    • How do I hide the settings button?
    • How do I keep elements from moving?
    • How do I list an element's connections in its profile?
    • How do I make elements transparent?
    • How do I make sense of my receipt?
    • How do I open a sub-system when clicking on an element?
    • How do I remove the Opposite entry from my legend?
    • How do I remove unneeded controls?
    • How do I remove unwanted legend entries?
    • How do I rename my map/view?
    • How do I restructure my adjacency matrix?
    • How do I select options by default in my control?
    • How do I set a minimum or maximum zoom level for my map?
    • How do I show the Settings button?
    • How do I size elements based on number of connections?
    • How do I transfer a project?
    • How do I update my credit card information?
    • How much data can my Kumu project handle?
    • How do my readers switch between maps and views?
    • My data won't import. What can I do?
    • My Kumu embed is not working. What can I do?
    • My map disappeared. How do I bring it back?
    • My PDF won't export. What can I do?
    • What pricing plans does Kumu have?
    • Where can I find my invoices?
    • Where can I find example Kumu projects?
Powered by GitBook
On this page
  • Why should I use selectors?
  • Where can I use selectors?
  • How do I write selectors?
  • Shorthand selectors
  • Longhand selectors
  • Pseudo-selectors
  • Traversals
  • Chain selectors

Was this helpful?

Edit on GitHub
  1. Guides

Selectors

PreviousProject adminNextShapes

Last updated 11 months ago

Was this helpful?

Selectors are a powerful tool, allowing you to select multiple items within your project based on the information stored in their .

Jump to a section:

Why should I use selectors?

In Kumu, you can always select items using your mouse and keyboard:

  • Clicking one element, connection, or loop to select it

  • Hold the shift key and click to select multiple items

  • Hold the shift key, then click-and-drag to select a group of items

Once you have an active selection, you can do all sorts of things: your selection, for your selection, on your selection, etc. Long story short, selections are extremely useful in Kumu!

But what if you need to select a large group of items that are densely interconnected with other items that you don't want to select? You can't hold shift & click-and-drag, because you'll select some unwanted items in that area. You could hold shift and click on each individual item, but that could take a reaaally long time for bigger maps.

The solution: selectors!

Think of selectors as a super-powered mouse & keyboard—they allow you to click on a lot of elements, connections, and loops extremely quickly and with perfect precision. Learning how to recognize, read, and write selectors will definitely come in handy when you're working in Kumu.

Check out the overview video below to learn the basics of selectors, then read through the rest of this guide for detailed instructions.

Where can I use selectors?

Search bar

You can use selectors in the search bar on your map to select multiple items.

If you'd rather write your selector instead of use the selector builder, just type an equal sign = in the search bar, then write your selector. Press enter on your keyboard to select all items that match your selector.

In the Basic Editor

The Connect By tool and decoration builder allow you to use the same selector builder from the search bar, and the filter and showcase tools allow you to either use the selector builder or write your own selector.

In the Advanced Editor

In all of the guides on this documentation site, keep an eye out for Advanced Editor instructions—they'll teach you how to use selectors to enhance all of Kumu's most powerful tools.

How do I write selectors?

In this section, we'll teach you how to write all kinds of selectors, which fall into these categories:

Shorthand selectors

Slugs

Universal selector

The universal selector is just an asterisk *, and it matches all elements, connections, and loops—everything on the map!

*       // select everything

Select elements, connections, or loops

Selecting all elements, connections, or loops is simple:

element                // select all elements
connection             // select all connections
loop                   // select all loops

Select by type

person                 // select all elements with "Person" element type
future-project         // select all elements with "Future Project" element type
personal-connection    // select all connections with "Personal" connection type
business-connection    // select all connections with "Business" connection type

Select by label

Selecting specific items by label is—you guessed it—pretty simple! Just turn the item's label into a slug, then add # in front of it:

#jeff-mohr             // select element "Jeff Mohr"
#thinking-in-systems   // select element "Thinking in Systems"
#b1                    // select loop "B1"

Select by assigned ID

If you have custom IDs in your project, you can use those IDs in shorthand selectors. The syntax is the exact same as the label selector: create a slug of the ID, then add # in front of it:

#project-1234          // select the item with id "project-1234"

Select by system ID

Behind the scenes, Kumu assigns a unique ID to each element, connection, and loop, as soon as you create the items. We call this a "system ID", and you can use this in shorthand selectors, too!

System IDs are created as slugs by default, so to turn turn them into selectors, all you need to do is add a # in front:

elem-1h04vQRH          // select the element with the system id "elem-1h04vQRH"
conn-9Gp2zuYg          // select the connection with the system id "conn-9Gp2zuYg"
loop-mt57r8Gb          // select the loop with the system id "loop-mt57r8Gb"

System IDs are guaranteed to be unique and permanent.

Select by tag

To select by tag, simply turn the tag into a slug, then add a . to the front of it:

.mission-critical      // select anything tagged with "Mission Critical"

Select by presence/absence of field values

The presence/absence selector allows you to select items based on whether they have any value or no values in a given field. To select by presence (any value in the field), turn the field name into a slug, and put it inside of square brackets:

[element-type]         // select any item with anything in the "element type" field

To select by absence (no values in the field), just follow the same steps, but put a ! in front of the field name's slug:

[!element-type]        // select any item (including connections and loops) with no value in the "element type" field

Longhand selectors

While the shorthand selectors are great for many cases, they're only supported for the fields and selections described above. For all other fields, or for more complex selections, you can use longhand selectors. Longhand selectors have three parts:

  1. Field name

  2. Operator

  3. Field value

And the syntax is as follows:

["field name" operator "field value"]

Replace field name and field value with a name and value from your project, depending on what you are trying to select, and keep them wrapped in "" double quotes. field name and field value are not case-sensitive in selectors.

Here are some examples:

["element type" = "person"] // select all items whose element type equals "Person"
["description" *= "kumu"]   // select all items whose description text contains "kumu"

When using the Type field in longhand selectors, you need to specify whether it is Element Type, Connection Type, or Loop Type. For example, use "connection type" instead of just "type" when selecting by connection type.

Here are a few more examples, using relative operators (greater-than, less-than, greater-than-or-equal-to, and less-than-or-equal-to):

[team-members < 20]         // select all items that have a number less than 20 in the Team Members field
[team-members > 20]         // select all items that have a number greater than 20 in the Team Members field
[team-members <= 20]        // select all items that have a number less than or equal to 20 in the Team Members field
[team-members >= 20]        // select all items that have a number greater than or equal to 20 in the Team Members field

Note also that these examples use team-members as the field name, instead of "Team Members". This works just fine, because you're allowed to use the slug of field-name instead of using "field name" wrapped in the double quotes. It's up to you!

You can also use relative operators with the built-in created and updated fields to select items by when they were created or most recently updated in Kumu:

[created > 2017]            // select all items that were created after the year 2017
[updated < 2017-10-01]      // select all items that were updated before October 1, 2017

Pseudo-selectors

Connected from and connected to

With the :from and :to pseudo-selectors, you can select connections based on the elements those connections are attached to. The basic syntax is :from(selector) and :to(selector).

To build your own, just replace selector with any valid selector. For example:

:from(organization)    // select all connections that are coming from elements with type "organization"
:to(#my-element)       // select all connections pointing to an element with the label "My Element"

Connection direction

Use the :directed, :undirected, and :mutual pseudo-selectors to select connections based on their direction.

:directed              // select all directed connections
:undirected            // select all undirected connections
:mutual                // select all mutual connections

Focus root

You can also select multiple elements or connections before you apply the focus effect. In that case, all the elements and connections you selected will be considered focus roots.

Use the :focus selector to select your focus root(s).

:focus                 // select all focus roots

Orphaned elements

In graphs and networks, an element that has zero connections is often referred to as an orphan. In Kumu, you can use the :orphan pseudo-selector to select all the orphans on your map.

:orphan                // select all orphaned elements

Loop contents

The syntax is an element or connection selector with :loop() at the end of it. You can also put a loop selector inside the parentheses to specify the loop or loops.

element:loop()                          // select any element that is part of any loop
*:loop(["loop type" = "reinforcing"])   // select anything that is part of a reinforcing loop

Not

The :not pseudo-selector is useful when you want to select items that do not match a selector. The basic syntax is :not(selector).

To build your own, just replace selector with any valid selector. For example:

:not(organization)       // select any item that doesn't have the element type "Organization"
:not(:orphan)            // select any item that is not an orphan, i.e. any item that has 1 or more connections
:not([tags ~= "blue"])   // select any item whose Tags field does not include the tag "blue"

Traversals

Traversals allow you to select elements based on the structure of your map. For example, you can select elements based on:

  • Which other elements they are connected to or from

  • The information stored in connection's profiles (including connection direction)

The basic syntax is selector arrow selector. You'll replace the first and last selector with any valid selector (including another traversal), and you'll replace arrow with one of the following options:

Arrow
Meaning

-->

Connected to

<--

Connected from

<-->

Connected to or from

Here are some examples:

person --> organization                     // Select all elements with the type "Person" that are connected to elements with the type "Organization"
person <-- organization                     // Select all people that are connected from organizations
person.democrat <--> person.republican      // Select all people tagged as Democrats who are connected to or from a person tagged as Republican

You can also add any valid connection selector inside of the arrow to specify exactly which connections are allowed:

element <--["field name" = "field value"]-- element       // Basic syntax for traversals. Select an element based on specific field information in the profile of a connection from another element
person.democrat --[strength > 5]--> person.republican      // Select all people tagged as Democrats who are connected to a person tagged as Republican, via a a connection whose strength is greater than 5

When you add connection selectors in the middle, be sure to put two dashes on the outside:

/* Two dashes, then a connection selector, then two more dashes. */
--strong-connection-->      // Connected to, via a connection with the type Strong
<--weak-connection--        // Connected to, via a connection with the type Weak
<--connection-->            // Connected to or from, via any connection

If you're writing a shorthand selector for connection type, for example, strong-connection, you can omit the -connection. Taking the example from above:

// These two selectors select the exact same thing
person.democrat --strong--> person.republican
person.democrat --strong-connection--> person.republican

Chain selectors

The selectors we've covered so far are building blocks. You can combine those building blocks to create complex queries involving AND and OR logic—this action is called chaining selectors.

Logic
Description
How to use in Kumu

AND

Only items that match all selectors in the chain will be selected

Write selectors back-to-back, with no white space or punctuation in between

OR

Items that match any selector in the chain will be selected

Join selectors with a comma

Here are some examples of selectors chained in different ways:

person[description]                         // select all items with the element type "Person" AND any value in the Description field

organization, person, project               // select all elements with the element type "Organization" OR "Person" OR "Project"

woman.young.influential                     // select all elements with the type "Woman" AND the tags "Young" AND "Influential"

:to(nonprofit):from(donor, foundation)      // select all connections leading to elements with the type "Nonprofit" AND leading from elements with the type "Donor" OR "Foundation"

:mutual[strength > 1]                       // select all mutual connections whose Strength is greater than 1

:directed[connection-type = "donation"]     // select all directed connections whose connection type is Donation

Before you start: to add additional information to your elements, connections, and loops.

In the upper left of the map, click "Search" next to the search icon to start searching. Then, click the rocket icon on the far right to bring up the selector builder, and use it to build out your selector.

There are several places in the where you can use selectors:

The is where selectors really shine. Advanced decorations, filters, focuses, controls—you name it! Almost every block of code in the Advanced Editor contains some sort of selector.

We'll also teach you how to to run complex queries involving AND and OR logic.

After you read this section, check out our —it's a great cheat sheet for every possible selector in Kumu.

You can also use our experimental to write selectors for you!

All shorthand selectors use slugs—pieces of text that have had all letters converted to lowercase, all special characters removed, and all spaces and replaced with hyphens. To learn more about recognizing, reading, and writing slugs, check out .

Selecting all of a specific type is pretty simple too. For elements, just take the element type and turn it into a . For connections, turn the connection type into a slug and add -connection.

In Kumu, you might sometimes assign custom, unique IDs—see our guide on for more info on when and why you would want to do this.

Then, replace operator with a logical operator recognized by Kumu, for example, = (equal to) or > (greater than). You can see the full list of operators and their meanings in the .

Pseudo-selectors allow you to select elements, connections, and loops based on information stored outside of their profiles—for example, in the profile of an adjacent element, or in the settings of your view.

When you click and hold on an element, you'll apply the effect to your map. The element you clicked will be the root of the focus, and the focus will extend a certain distance away from the root.

If you're using in your map, you can use the :loop pseudo-selector to select elements and connections that are part of a specific loop or loops.

use fields
Filter tool
Connect By tool (clustering)
Showcase tool
Decoration builder
selector reference
selector builder interface
our full guide on slugs
slug
avoiding duplicates
focus
focus
loops
Shorthand selectors
Longhand selectors
Pseudo-selectors
Traversals
chain selectors together
fields
decorate
focus
Why should I use selectors?
Where can I use selectors?
How do I write selectors?
change field values
Basic Editor
Advanced Editor
selector reference
selector rocket