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
  • Add controls through the Basic Editor
  • Add controls through the Advanced Editor
  • Remove unneeded controls
  • Built-in controls

Was this helpful?

Edit on GitHub
  1. Guides

Controls

PreviousClusterNextCluster control

Last updated 7 months ago

Was this helpful?

Controls allow you to customize how people interact with your maps by adding buttons, dropdowns or toggles to your map. You can also use them to overlay metrics, images, text and more on! Interactive controls can be used to transform the current view's setting too, such as filter, focus, and clustering.

Want to dive a little deeper into controls? Check out our

Add controls through the Basic Editor

Use the dropdown menus in the controls builder to set up your control, then, when you're done, click the back arrow to return to the main screen, and click SAVE.

Add controls through the Advanced Editor

@controls {
  top {
    showcase {
      by: "Element type";
    }
  }
}

In general, controls are defined with the @controls block, grouped into regions, and customized using properties. You can add multiple controls to a region, and even override or move Kumu's built-in controls. Here's the general syntax that shows how multiple regions can be used, and how multiple controls can be added to the same region:

@controls {
  region {
    control {
      property: value;
      property: value;
      ....
    }

    another-control {
      property: value;
      property: value;
      ...
    }
  }

  another-region {
    some-other-control {
      ...
    }
  }
}

Regions

Adding a custom control to your map starts by picking where you want to place the control. Controls can be assigned to one of six regions on the map:

  • top

  • top-left

  • top-right

  • bottom

  • bottom-left

  • bottom-right

@controls {
  top-left {
    title {
      value: "This map has a title!";
    }
  }
}

Control type

After you set the region, you can choose what type of control you are adding. Here are the available control types:

Properties

Controls are customized using properties, and each control understands a slightly different set of properties. In the example below, by is a property of the showcase control that accepts a field name (wrapped in quotes).

@controls {
  bottom {
    showcase {
      by: "Element type";
    }
  }
}

Children

Sometimes, controls need to work with complex lists of options. Since these would be overwhelming to define in a single line, the items are included as children of the control instead, and follow a similar syntax to the controls themselves.

In the example below, we call the option blocks the "children" of the showcase control, and each child includes its own set of properties.

@controls {
  top-left {
    showcase {
      option {
        label: "People";
        selector: person;
      }

      option {
        label: "Orgs";
        selector: organization;
      }
    }
  }
}

You can read through the individual control guides (linked above) to see which controls accept children and which properties their children understand.

Groups

By default, controls are each stored on their own line, and they each have their own set of properties. However, if you want to display a group of controls on one line (for example, along the top of your map), and assign a few common properties and values (for example, font-size: 16) to all of them, you can use groups.

To group controls, use the following group syntax:

@controls {
  region {
    group {
      property: value;

      control {
        property: value;
        property: value;
        ...
      }
      another-control {...}
      an-additional-control {...}
    }
  }
}

The properties that get set underneath group will apply to all controls nested inside the group. And before you ask—yes, it's possible to nest groups inside of other groups as well!

Remove unneeded controls

Basic Editor

  1. When hovering over an existing control, click on the edit pencil to edit your existing control, or click on the trash icon to delete it.

Advanced Editor

// Line 1 of your Advanced Editor:
@controls {
  ...There will be other code inside this block
}

If you don't want any controls or "No values found for [some field name]" messages on your map, simply delete the entire @controls block, then click "Save" at the bottom of the editor.

If you have some controls in there that you would like to preserve, you'll first need to learn the basics of how to read @controls code, so that you can tell which controls you want to delete and which you want to keep.

  • If you want to delete all controls in a certain region of your map, then delete all the code saying top, or top-left, or bottom etc. Delete the whole block to delete all the controls in that region.

  • If you want to delete just one control, locate it in the list of your controls and delete that whole block. You can recognize a control block by the fact that the first line is filter, or showcase, or cluster, or focus.

Built-in controls

Although you won't see it in your Advanced Editor, here's the default @controls code working behind the scenes:

@controls {
  top-left {
    search {}
  }

  top-right {
    zoom-toolbar {}
    settings-toolbar {}
    focus-toolbar {}
  }

  bottom-left {
    legend {}
  }
}

You can omit individual controls by including the region in your @controls block, without the control inside of it. For example, if you wanted to keep the search bar, but omit all other built-in controls, you could use:

@controls {
  top-right {}
  bottom-left {}
}

Note that if you add controls to a region in your code, but don't explicitly include the default control, it will be hidden. For example, this code will hide the zoom-toolbar, settings-toolbar, and focus-toolbar:

@controls {
  top-right {
    title {
      value: "Oops! I hid some useful controls.";
    }
  }
}

If you want to quickly start from scratch without any of Kumu's built-in controls, you can use reset: true.

@controls {
  reset: true;

  top {
    title {
      value: "Check out my custom controls";
    }
  }

  bottom {
    showcase {
      by: "Element type";
    }
  }
}

You can use the to add a few simple types of controls to your map. Click the settings icon to open the editor, then click Add custom control. Kumu will open up the controls builder, with a few options pre-selected:

Want to remove unneeded controls? You can use the section of this guide to help troubleshoot.

To unlock the full set of flexible controls features, you can use the . Here's an example of what controls look like in the Advanced Editor:

title:

text:

label:

showcase:

filter:

Focus:

cluster:

tagged-timeline:

color-legend:

image:

sna-dashboard:

view-toggle:

For a full list of the properties that each control understands, read the individual control guides (linked above), or check out the .

Looking to change the order of the controls in your map? Have a look at .

When you're adding through the Basic Editor, you might sometimes add a duplicate control by accident, or add a control that says "No values found for [some field name]". You can remove controls through the Basic Editor and the Advanced Editor.

Click the settings icon on the right to open the Basic Editor, then scroll down to "Add custom control". You'll see all existing controls listed out below.

Open up the Advanced Editor (click Settings and then choose Switch to Advanced Editor at the bottom). Unless you have added , there will be a block of code right at the top starting with @controls.

You can learn more about reading @controls code in . Of course you can always send us an email at support@kumu.io to help out!

All of Kumu's built-in controls (search, zoom buttons, settings buttons, the ) are handled by the same platform that custom controls are built on. That means you can move the built-in controls around, omit ones you don't need, or even reset the built-in controls and start from scratch.

Title control
Text control
Label control
Showcase control
Filter control
Focus control
Cluster control
Tagged-timeline control
Color-legend control
Image control
Social Network Analysis Dashboard control
View toggle control
controls reference
this guide
controls
legend
remove unneeded controls
our full guide on controls
Taking Control of Kumu webinar
partial views
Advanced Editor
Basic Editor
controls builder ui