How-to: Get started with Subform


Getting started with Subform

Get familiar with the basic concepts behind Subform and start thinking responsively, while you design.


In Subform, you can create layout rules and relationships that help you establish your design intent: how much space is between elements, how an element should stretch when the screen gets bigger, and so on.

This guide covers some of the basics of Subform’s layout system—enough to get you up-and-running quickly.

Adding boxes, text & images

To add a box to the artboard, click the Add Box Mode button in the app toolbar. Like traditional drawing tools, you can simply click-and-drag out a box to your desired dimensions:

To exit the box adding mode, just hit esc or press the Add Box Mode button again.

Adding a box this way makes it a self-directed element: you can drag and resize it in a freeform manner. You can also add boxes that are parent-directed: their layout is controlled by their parent and takes into account other elements.

Enter Add Box Mode again and instead of dragging, try clicking on the artboard a couple times. You’ll see that boxes are added in a stack—the more boxes you add, the smaller they get.

You can also add boxes inside of other boxes by hovering over them and then clicking. Adding boxes this way is great for quickly sketching out interface elements.

To add text, click the Add Text button in the app toolbar, or press T. A text box will be added as a child of the element you currently have selected.

To add images, click the Import Images button in the app toolbar, then select an image from your filesystem. Images are always imported as self-directed elements at their native size.

Parent-child relationships

On the left side of the Subform UI, you’ll see the Tree tab. This works much like a traditional layers panel, except that it exposes the structural relationships between elements. When you drag one element into another in the tree, that element becomes a child of the parent element into which it was dragged.

In the above example, text and an icon are dragged into a button element. Now when you move that button around the artboard or duplicate it, its children will come along. This is similar to a group in Sketch or Photoshop.

Unlike groups, however, parent elements can control the layout of their children. Right now, the icon and text are centered in the button. What if you wanted to horizontally align them both to the left side?

When you select the button element, you’ll see the Children Layout control group on the bottom right side of the Subform UI, under the Layout tab.

With children layout controls, you can affect the spacing and alignment of all the children in a parent at once. To left-align the icon and text, we’ll set the main axis space before to be 10. The main axis space after will be set to 1s_10, which means the right side should take up all the available space (“stretch”), but have a minimum value of 10. We can also add some more spacing to the top and bottom of the button by setting the cross axis space before and after to similar values.

Don’t forget that self-directed elements ignore their parent’s children layout settings. They control their own layout and aren’t affected by any of their siblings.

Layout types

Another important setting in the Children Layout control group is the layout type. Parents can arrange their children in one of three ways:

In a horizontal stack, elements are arranged in a line from left to right. The main axis determines element width, while the cross axis determines element height.

In a vertical stack, elements are arranged in a line from top to bottom. The main axis determines element height, while the cross axis determines element width.

In a grid, elements span one or more columns and rows. The grid settings on the parent determine the number of columns, rows, and the grid gutters and margins. Elements can be moved around the grid by dragging and resizing:

If you only have one child in a parent, you won’t notice any visual change when you switch between horizontal and vertical stacks. Add a second child to see the difference.

When you add children to a grid, they’ll always start off in the top left cell. Elements can overlap in grids, so use the tree if you can’t find the element you’re looking for.

Stretch & hug units

You make elements responsive in Subform by using the stretch unit, s. While 100 is an absolute value, 1s is a relative one. Its exact size can vary, depending on its relationships with other elements.

Imagine you have two boxes, both set to a width of 1s. Instead of being fixed, the boxes now stretch in width to take up all the available space, even as the window resizes:

In this case, both boxes are dividing up the available space evenly. What if you wanted the first box to be three times as wide as the second one? Change its width to 3s:

The first box will now always be three times wider than the second box, but they both still stretch out to make sure all of the available space is used up. Specifying sizes and spaces this way is an important part of creating responsive UIs, so be sure to read more about how Stretch units work.

Another unique sizing unit in Subform is hug. Use this unit (with no number value) when you want a parent element to take on the size of its children, or hug its content. A classic example is when you want a button to automatically resize when its label gets longer or shorter:

Head-up display (HUD)

Sometimes it can be difficult to tell exactly how the layout rules are affecting the element you have selected. That’s where the HUD comes in. You can toggle it on and off by pressing the alt key:



@Ryan it looks like this button title has changed to "Import Images" in the current build of Subform. :grin:


Thanks, @benzo. Fixed.


This link doesn’t work.


Thanks for catching that, Alex! It’s fixed now.

2017.12.04 Subform release 4240

@Ryan This seems to only add boxes with 0x0 dimensions. (Mac)


I have the same issue with the windows version, I’m glad to know I’m not the only one!


@peterdarthur @astrid.boivin Sorry about that, our development has unfortunately outpaced our getting started videos. :confused:

We’ve removed the old add-box mode in favor of a simpler drawing mode that more closely matches existing tools. We do intend to introduce the old box mode back into the tool again, but for now there are a few options to add boxes:

  1. Use the “Add Box” button in the toolbar to draw out a box and then move it into the parent where you’d like it to be placed. (For more information on this, check out the video on this post.)

  2. Press “enter” when you have a parent selected and a box will be added inside of that parent. (You can press enter multiple times to add multiple boxes)

  3. Use the “Insert->Self directed box” or “Insert->Parent directed box” menu items to add a child box to the parent you currently have selected.

Hope that helps, if you have more questions just let me know.


Perfect! Wow! Thanks for the quick and thorough reply! I love that feature, adding children with automatic proportions and scaling, with just one key press! :drooling_face: :star_struck: Move over, .psd and .sketch !


I had look in that menu but hadn’t understand that it did the same thing! This is like THE feature I was eager to check on so I was a bit disappointed it didn’t worked like in the video at first :stuck_out_tongue:

That would be awesome to bind it to a keyboard shortcut so you can easily click + [shortcut] and have a parent directed or a self directed box!


Great feedback, thanks! We definitely want to add advanced-mode improvements back in—they really speed up the rough creation of layouts.


For anyone else having a little trouble with “hug” - it only works for me when it’s set on both the parent and child widths (or heights), and when the child is set to parent-directed. Setting “hug” on just the parent width or just the child width doesn’t seem to work.


A few things to keep in mind that might help with this:

  • Self-directed elements effectively ignore their parent’s layout rules. If the parent width or height is set to hug and only has self-directed child(ren), it’s the same as having no child—the parent doesn’t have any children that are playing by its layout rules.

  • A parent hug should otherwise work with parent-directed children that have a fixed width (e.g. 200) or a stretch width with a minimum size (e.g. 1s_200).

  • If a child has a stretch width with no minimum, or a percentage width, it’s width is variable… it’s looking up to the parent to see how wide it should be. (e.g. 50% of the parent) If the parent width is set to hug, it’s looking down to its children to see how wide it should be. This can create a cyclical error because they’re both depending on each other. There needs to be a fixed value in there somewhere.

I know this stuff can be a lot to internalize when you’re just getting started, so I’m happy to answer more questions or take a look at the file you’re working on.


Thanks again for the quick reply!

It still seems to be giving me issues, even with a max/min set on the child. Here are my settings:


  • Type: Box
  • Positioning: Self-Directed
  • Horizontal: 1s - hug - 1s


  • Type: Text
  • Positioning: Parent-Directed
  • Horizontal: 1s - 1s_20^400 - 1s

For some reason, the parent box only expands to the minimum 20, and doesn’t change width when the child’s text overflows it, unless I change the Child’s Horizontal Width value also to “hug”. I tried this in a new artboard, with only the one parent and child, just to be sure it wasn’t another setting that interfered.


@peterdarthur I’m going to cross-link over to this topic that was just posted: How to create a hugged text container

Is that design intent similar to what you are trying to accomplish here? Or is it something else? If you can clarify what you expect to happen a bit, that’ll help us suss this out.

In general, a hug parent with a stretch child will always resolve to the minimum. (That’s why we call it hug—it squeezes as tightly as possible. :slight_smile: ) If you set the text child to have a fixed width, say, 400, then the parent will hug to that exact size.


Thanks, @Ryan, that is what I would like to accomplish as well, just like in the video about hug above. I’ll check that topic from now on. :+1:


Hi there! I’m brand new with Subform, but I can’t seem to be able to add text to an element with the T shortcut or the “Add text” button. Even if I have an element selected, if I do either of these actions, I can only draw a text area that is placed at the artboard root level. Am I missing something obvious?



Ok, I’ve found how to do it by reading it in another post… ctrl-t is the way to go! It’s also in the insert menu. It just didn’t fit with the tutorials (I can understand that, with rapid pace development). Is there a central place where all hotkeys are listed?


Hi @david.savoie, welcome! There isn’t a single place that has all of the hotkeys listed — your best bet is to look through the application menu (on top of the screen on Mac, on top of the window on Windows).

Another helpful tip for learning is to click on any underlined text in the sidebar, and that’ll bring up more explanation and inline GIFs explaining the concepts.
For example, this is the window that came up when I clicked on the “Layout Type” label: