Lists & Indices

When you drop a slider on the canvas and wire it into a component, it feels like you are passing a number. You are not - you are passing a list that happens to have one item. That reframing matters, because the moment you divide a curve, draw a grid of points, or copy an object, that single wire starts carrying many items at once, and every downstream component treats the whole stream at the same time.

A list in Grasshopper is simply an ordered collection of items travelling down one wire. Order is the whole point. The list ["door", "window", "wall", "roof"] is not the same as ["roof", "wall", "window", "door"], even though both contain the same four things - because components read them in the order they arrive. When you Divide Curve into 10 segments, you get a list of 11 points in a definite sequence from the curve's start to its end. That sequence is not decoration; it is data you will rely on.

Hold the mental image the whole course leans on: one flowing list, left to right, item after item. Master the single list and the data tree in the next lesson stops being frightening - a tree is just a filing cabinet of these lists.

Every item in a list has an address called its index, and in Grasshopper - as in almost all programming - indices start at 0, not 1. The first item is index 0, the second is index 1, and a list of 5 items has indices 0 through 4. Its List Length is 5, but its last index is 4. That off-by-one gap between length and last index is the single most common beginner stumble, and naming it now will save you hours.

The List Item component is how you pull one item out by index: feed it a list and an index i, and it returns the item sitting at that position. Ask for index 0 and you get the first; ask for the length (say 5) and you get nothing, because there is no item there - you have walked one step off the end. Want the last item reliably, whatever the length? Feed List Item a negative index (-1 wraps to the last item) or compute length - 1 with a subtraction. Both are honest habits; guessing the index is not.

List Length answers 'how many?', and you will wire it into more things than you expect: to place the last object, to size a range, to check that two streams are the same length before you combine them. When something downstream breaks, the first question a seasoned user asks is not 'what's the shape?' but 'what's the length, and is index 0 what I think it is?'

You will constantly need a list of numbers to drive something - counts, spacings, parameters from 0 to 1. Two components make them, and confusing them is a rite of passage.

Series builds a list from a start, a step and a count: start 0, step 3, count 4 gives [0, 3, 6, 9]. You control the spacing directly and the count tells it when to stop. Reach for Series when you know 'give me 20 values, each 4 units apart'.

Range divides a domain (a from-to interval) into a number of equal steps: the domain 0 to 10 with 5 steps gives [0, 2, 4, 6, 8, 10] - note that N steps produce N+1 numbers, because you get both fences and the posts between them. Reach for Range when you want 'evenly spaced values across this interval', especially the classic 0-to-1 parameter list that drives colours, heights, or positions along a curve.

The honest rule of thumb: Series when you know the step, Range when you know the endpoints. Both hand you a clean list; which one you pick decides whether you think in increments or in bounds. Feed either into Point, Move, or Evaluate Curve and you have turned a rule into a rhythm of geometry.

Once you have a list, a handful of components reshape it - and each one changes the indices, which is exactly why they solve so many problems and cause so many.

Reverse List flips the order: [0, 3, 6, 9] becomes [9, 6, 3, 0]. Useful when a curve was drawn the 'wrong' way and your points march from the wrong end.

Shift List slides every item along by an offset, optionally wrapping the ends around. Its quiet superpower is pairing each item with its neighbour: shift a list of points by one and combine it with the original, and you have the start-end pairs for every segment of a polyline - the trick behind connecting dots into lines.

Cull removes items. Cull Pattern takes a repeating true/false mask (True, False) and keeps only the trues, thinning a list to every other item; Cull Index drops specific positions. This is how you punch holes in a grid or skip every third louvre.

Sort List reorders items by a key - a second list of numbers that ranks them. Crucially, Sort List can carry passenger lists along: sort a list of distances and let the matching geometry ride in the same order, so your objects end up arranged nearest-to-farthest. That pattern - sort geometry by a measured value - is the engine behind attractor effects you will meet later.

The common thread: all four rewrite which item lives at which index. After any of them, re-ask the length-and-position question before you trust the next step.

Let's tie the pieces into one small workflow you'll do a hundred times, because seeing lists earn their keep makes the abstraction concrete. Say you want a zig-zag screen: a row of points, connected in order, then given depth.

Start with a Range on the domain 0-to-1 with, say, 12 steps - that's 13 evenly spaced parameters. Feed them into Evaluate Curve along a base curve and you have 13 points marching from one end to the other, in a definite order. So far, one clean list.

Now connect them. A Polyline through the list draws a single line visiting the points in sequence - and here the order you spent this lesson mastering is doing the work; reverse the list and the polyline still connects the same dots but the direction flips, which matters the moment you offset or extrude it. Want individual segments instead of one polyline? This is where Shift List shines: shift the points by one, then feed the original list and the shifted list into a Line component, and each point pairs with its neighbour to give you 12 separate segments. That neighbour-pairing trick - born entirely from list order and a shift - is one of the most reused moves in all of Grasshopper.

Finally, thin it: drop a Cull Pattern (True, False) before the polyline and you've halved the density to a sparser rhythm, no rewiring required. Notice what just happened - you designed a system (points, order, connection, density) whose every knob is a list operation. That is the whole promise of the last lesson made tangible, and it's built entirely from the handful of components you now know.