LED strips are a fantastic way to add vibrant and dynamic lighting effects to any project. Whether you’re designing a set for an attraction, building robots and animatronics or realistic props, LED strips can help you achieve your vision. But programming these LED strips to display custom patterns and animations can seem like a daunting task if you’re just getting started with microcontrollers like the Arduino or have never programmed anything at all.

Sure, there are plenty of LED kits on the market that come with a remote control and pre-programmed colors that you can choose from. But the vast majority of these kits can at best cycle through a single color at a time and maybe give you some basic flashing effects. Your project deserves more. In this tutorial, we’ll explore how to use the FastLED library with Arduino to program LED strips, creating a wide range of lighting animations with ease. Whether you’re a beginner or an experienced maker, this guide will help you unlock the full potential of your LED strips and bring your project to life.

In order to get started, connect your LED strip to both your Arduino and power supply, and then fire up the Arduino IDE. If you’re an absolute beginner and never hooked up anything before or coded with Arduino you have nothing to worry about! You can download the Arduino IDE for free from the Arduino website and get familiar with the program and how Arduino sketches work by checking out my Arduino IDE & Uploading Your First Sketch tutorial. If you need help with getting the different components wired and connected properly, review my previous step-by-step tutorial on how to connect and power an LED strip with Arduino which also includes a wealth of information about LED strips to help you select the best one for your project. Then, join us back here to start programming your first animations!

Install the FastLED Library

The FastLED library can be installed right from the Arduino IDE! Just navigate to Sketch > Include Library > Manage Libraries. From there, start typing FastLED into the search box and you should see the FastLED library show up as the first choice. Go ahead and install the latest version. Sometimes when you install a new library it won’t work until you restart the Arduino IDE. You’ll can either do this now so you’re ready to go, or later once we start coding. With any library, you’ll notice that the library’s keywords won’t change color like they’re supposed to if the library is not recognized. That’s an indication to try and restart the program and that usually resolves it.

How to Get Started with the FastLED Library

With the library installed, let’s set up some parameters in our Arduino sketch so we can begin programming our animations. I’ll take you through all the necessary code to get your animations working but if you would like further reading, the official documentation for the FastLED library can be found here: FastLED Wiki

Step 1: Include the FastLED Library

The first step in writing our sketch is to include the FastLED library. This will allow us to use a variety of functions written specifically for controlling LED strips that aren’t a part of the standard Arduino IDE. To include a library in a sketch go to Sketch > Include Library > FastLED. You’ll notice a new line of code pop up at the very top of your sketch:

 #include <FastLED.h>

Step 2: Define Hardware Setup

Next, we’ll need to define some global variables that tells the FastLED library about our hardware setup like type of LED chipset we’re working with, number of pixels in our strip and where the data line is connected. Place this code block below the line that includes the FastLED library and above the void setup() function.

 #define NUM_LEDS 20
 #define LED_PIN 2

 CRGB leds[NUM_LEDS];

#define NUM_LEDS 20

In this line of code we define how many pixels we want to control. For this example there are 20 pixels in our LED strip. If you had 100 pixels in your strip then replace 20 with 100 and the line of code would look like this:

#define NUM_LEDS 100

#define LED_PIN 2

With this line, we’re telling the FastLED library what pin of the Arduino the LED strip’s data line is connected to. In our example, the data line is connected to pin 2 on the Arduino. Simply change 2 to whatever pin you’re using. If you’re using pin 6, then this line of code would look like this:

#define LED_PIN 6

CRGB leds[NUM_LEDS];

Finally, we create an array which is a collection of variables that are accessed with an index number. You’ll see this in action a little later which will make it easier to understand. But for now you can think of it as a map of our pixels along the strip from beginning to end that we can manipulate to set and clear LED data. Using an array allows us to select specific pixels on the LED strip, a particular group of pixels on the strip or the entire strip. You’ll notice that I put NUM_LEDS inside the brackets [] which we already defined above as 20 pixels which means we want to include all the pixels in the array. You can name the array whatever you want but you’ll commonly see it just called leds. For instance, if you wanted to name your array bob it would look like this:

CRGB bob[NUM_LEDS];

Step 3: Setup () Function

The last step is to initialize the LEDs using the variables we defined above to tell the FastLED library what chipset we’re using. You can also set overall brightness for your entire LED strip along with a pause before the animation gets started. Adding the delay() is optional but good practice to protect the LED strip from any errors or power spikes on startup.

 void setup () {
  FastLED.addLeds<WS2812B, LED_PIN, GRB>(leds, NUM_LEDS);
  FastLED.setBrightness(50);
  delay(2000);
 }

FastLED.addLeds<WS2812B, LED_PIN, GRB>(leds, NUM_LEDS);

In this line of code we’re giving the FastLED library a lot of information about our LED strip. The first bit of information is what chipset we’re working with. FastLED supports a variety of SPI and 3-wire chipsets and in this example, we have an addressable LED strip with the WS2812B driver chip. Next we specify the Arduino pin the LED strip is connected to. You can either put a pin number in here or use a variable like I did called LED_PIN which we already defined as pin 2. Finally, we have to tell the FastLED library what color order our LEDs are in within the pixel. It won’t always be RGB. With the WS2812B type, it’s usually GRB, or green, red, blue. Don’t know what color order your LED strip is? No problem – I’ll show you how to find out a little later in this FastLED tutorial. If you’re also using a WS2812B LED strip, leave it as GRB because this is the most likely scenario.

Finally, we add information about our array in parenthesis – the array name and number of pixels that make up the array. In our case our array is called leds and has NUM_LEDS pixels in it which we defined as 20.

FastLED.setBrightness();

You can set an overall brightness for your entire LED strip with this line of code. In the parenthesis, insert a number from 0 to 255, 0 being off and 255 being full brightness. You can override this later on in the code if you want but this gives the LED strip a starting point. If you plan to make a video of your animation, I recommend turning down the brightness because the colors show up more accurately without getting blown out on camera.

How to Determine an LED Strip’s Color Order

Before starting with our first animation, it’s a good idea to double check that we have the correct color order. Some manufacturers change up the wiring and RGB ordering so colors may not display correctly. This is usually the case with the WS2812B LED strips. In order to check your color order, use this code in your loop () function:

 void loop () {
  leds[0] = CRGB::Red;
  leds[1] = CRGB::Green;
  leds[2] = CRGB::Blue;
  FastLED.show();
 }

array[x] = CRGB:: ColorName;

You’ll notice that the first three lines of code in the loop () function all have the same basic structure. First you specify the array you want to manipulate – in our case our array is called leds. In the brackets [] you identify what pixel you want to affect. When using arrays, the very first pixel is actually number 0 so in the code above I’m telling the Arduino to turn the first pixel (number 0) to the color red, the second pixel (number 1) to green and the third pixel (number 2) to blue. The colors must be written with the correct capitalization in order to be recognized.

The CRGB portion of the code is an object representing a color in the RGB color space. One of the beginner-friendly features of the FastLED library is that it comes with a list of over 100 pre-defined colors to choose from that use common color names rather than having to code out a mix of red, green and blue to create custom colors. We’ll cover more advance color manipulation in the next tutorial. But for now, using pre-defined colors is an easy way to get started because whatever color name you choose, the CRGB object will put out the correct mix of red, green and blue to achieve it. We’ll explore more colors from the pre-defined color list in the examples section of this FastLED tutorial.

FastLED.show();

Getting colors to show up on an LED strip is a 2-step process. We’ve already completed the first step in identifying what colors we want and what pixels are going to show them. But for now, this information only exists in the Arduino. In order to push out these instructions to the LED strip, we use the FastLED.show() command.

The complete sketch including all the parts we’ve talked about so far to determine your LED strip’s color should look like this:

 #include <FastLED.h>

 #define NUM_LEDS 20
 #define LED_PIN 2

 CRGB leds[NUM_LEDS];

 void setup () {
  FastLED.addLeds<WS2812B, LED_PIN, GRB>(leds, NUM_LEDS);
  FastLED.setBrightness(50);
  delay(2000);
 }

 void loop () {
  leds[0] = CRGB::Red;
  leds[1] = CRGB::Green;
  leds[2] = CRGB::Blue;
  FastLED.show();
 }

Upload your sketch to the Arduino and look at what colors you see on the first three pixels of your LED strip. The colors should show up in the same order as you specified in the code.

If it does not, then update the color order in the setup () function to match what you see on your strip. For instance, if your LED strip shows green for pixel number 0, blue for pixel number 1, and red for pixel number 2 then your code in the setup () function would look like this:

FastLED.addLeds<WS2812B, LED_PIN, GBR>(leds, NUM_LEDS);

FastLED Examples

Now that we have our LED strip set up properly, it’s time to begin coding our first animations! There are many ways to specify and control colors with FastLED, but in these examples we’ll be using colors from the FastLED library’s pre-defined color list. It’s a beginner-friendly way to get started and makes it easier in the future to jump into more complex ways of manipulating color. I’ll also go over some handy functions that are specific to the FastLED library that makes performing certain operations easier with one line of code.

You can substitute any color from the pre-defined color list you want for the FastLED examples below. There are over 100 colors to choose from. Be sure to use the correct capitalization in the code, just as it appears in the documentation. Check out all the pre-defined color choices in the Pixel Reference.

Blink a Pixel on an LED Strip

Blinking individual pixels on an LED strip works a lot like blinking a regular LED with the Arduino. Let’s blink the first pixel in our strip the color red at a rate of half a second. Keeping the setup () function the same, the loop () function would look like this:

 void loop () {
  leds[0] = CRGB::Red;
  FastLED.show();
  delay(500);

  leds[0] = CRGB::Black;
  FastLED.show();
  delay(500);
 }

Anytime you want to turn a pixel off, use the color Black. You’ll notice that we have to use FastLED.show() every time you change colors. It’s kind of like the digitalWrite function we use for regular LEDs.

Basic Scanner Effect

Let’s get our lonely pixel to travel up and down the LED strip. You can accomplish this with for loops and by tweaking the delays you can control how fast the color dot moves down the strip. Try faster values for a more realistic scanner effect. Here’s what the loop () function would look like:

 void loop () {
  for (int i = 0; i < NUM_LEDS; i++) {
   leds[i] = CRGB::Red;
   FastLED.show();
   delay(100);
   leds[i] = CRGB::Black;
  } 

  for (int i = NUM_LEDS-1; i >= 0; i--) {
   leds[i] = CRGB::Red;
   FastLED.show();
   delay(100);
   leds[i] = CRGB::Black;
  }
 }

In the first for loop, the red dot moves from position 0 to position 19. Keep in mind that NUM_LEDS is 20 so you’ll see that I set i < NUM_LEDS so it would only light up until position 19. In the second for loop we start at i = NUM_LEDS-1 which is 20-1. This gives us our position 19 starting position and the red dot works itself back down to the beginning, ending at position 0. The loop then repeats to give you a back and forth scanner effect.

Color Chase Effect

The scanner effect looks great on shorter LED strips but for longer runs, much of the strip will be off most of the time. The color chase effect is a more dynamic way to move color through the strip using all the pixels. Here’s what the loop () function would look like:

 void loop () {
  for (int i = 0; i < NUM_LEDS; i++) {
   leds[i] = CRGB::Red;
   FastLED.show();
  } 

  for (int i = NUM_LEDS-1; i >= 0; i--) {
   leds[i] = CRGB::Green;
   FastLED.show();
  }

  for (int i = 0; i < NUM_LEDS; i++) {
   leds[i] = CRGB::Blue;
   FastLED.show();
  }

  for (int i = NUM_LEDS-1; i >= 0; i--) {
   leds[i] = CRGB::Cyan;
   FastLED.show();
  }
 }

In the first for loop, the red dot moves down the strip but the previous pixels stay lit. When it reaches the end of the strip, a green dot begins moving in the opposite direction, changing the previously lit red pixels to green. This process repeats with blue and cyan before looping back to the beginning of the animation.

Fill an LED Strip with a Solid Color

The FastLED library has a variety of color-control functions to help you animate faster. If you simply want to fill all the pixels in your strip with the same color or animate between solid colors, you can always use for loops but the FastLED library has a special function just for this purpose.

fill_solid (array, number of LEDs, color);

This function takes a few arguments within the parenthesis. The first one you have to specify is what array you want to affect. In our case, our array is called leds. The second parameter wants to know how many LEDs in that array you want to include. I want to include all 20 of my pixels so I’ll use NUM_LEDS since we already specified it as a variable. Finally, choose the color we want to fill our pixels with. Here’s an animation that cycles through a few solid colors:

 void loop () {
  fill_solid (leds, NUM_LEDS, CRGB::Red);
  FastLED.show();
  delay(500);

  fill_solid (leds, NUM_LEDS, CRGB::Green);
  FastLED.show();
  delay(500);

  fill_solid (leds, NUM_LEDS, CRGB::Blue);
  FastLED.show();
  delay(500);
 }

This animation cycles through red, green and blue and shows each color for 500ms using the delay() function. Although solid colors can seem pretty basic, they can make a huge impact when creating an overall theme or mood for an attraction or visual interest for props and costumes.

Fill an LED Strip with a Gradient of Colors

Let’s add a bit more interest to our solid color animation by adding a gradient effect between different color blocks along the LED strip. The FastLED library has another handy function to make this lighting animation simple.

fill_gradient_RGB (array, number of LEDs, color 1, color 2, color 3, color 4);

The arguments in the parenthesis should now look familiar to you. We start by specifying the array, leds in our case. Then the number of LEDs we want to include which is NUM_LEDS for us. Then you can choose either 2 or 4 colors to fill your LED strip with and it will create a nice gradient transition between them. When working with the pre-defined colors, trying to include just three colors causes some erratic behavior like constant rebooting of the microcontroller or an unresponsive LED strip. Hopefully it’s a bug that will be resolved soon. The workaround is to specify the colors using other methods which we’ll cover in a later tutorial. Here’s an animation showing four color blocks move down the strip:

 void loop () {
  fill_gradient_RGB (leds, NUM_LEDS, CRGB::Yellow, CRGB::Magenta, CRGB::Blue, CRGB::Green);
  FastLED.show();
  delay(500);

  fill_gradient_RGB (leds, NUM_LEDS, CRGB::Green, CRGB::Yellow, CRGB::Magenta, CRGB:Blue);
  FastLED.show();
  delay(500);

  fill_gradient_RGB (leds, NUM_LEDS, CRGB::Blue, CRGB::Green, CRGB::Yellow, CRGB::Magenta);
  FastLED.show();
  delay(500);

  fill_gradient_RGB (leds, NUM_LEDS, CRGB::Magenta, CRGB::Blue, CRGB::Green, CRGB::Yellow);
  FastLED.show();
  delay(500);
 }

You can pick vibrantly different colors to draw attention to certain areas of your attraction or prop, or use colors with subtle differences to enhance a specific color palette.

Fill an LED Strip with a Rainbow of Colors

So far, we’ve created some impressive lighting animations with just single colors using for loops and FastLED library functions. But what about displaying all the colors along an LED strip? As you may have already guessed, the FastLED library has a simple function for showing a rainbow of colors in one line of code.

fill_rainbow (array, number of LEDs, starting hue, delta hue);

This FastLED function takes some different parameters than the others. First we specify the name of the array we’re working with, which is leds. Then, the number of LEDs in the array, which in our case we’ll use the NUM_LEDS variable name to include all 20 in our sample LED strip. Next, select the color you want your rainbow to start with as a hue value.

So far we’ve been specifying colors from the pre-defined FastLED library color list like Red, Magenta, Yellow, etc. Colors can also be specified using hue values from 0 to 255. From the chart below you can see that 0 corresponds to red and 255 is purple before looping back to 0.

We’re going to get into more detail about using hues in the next FastLED tutorial because it gives us far more control over animating colors than the pre-defined colors method we’ve been using so far.

But getting back to our example, I want to fill my 20-pixel strip with all the colors of the rainbow so it would make sense to give my starting hue a value of 0 for red. The last parameter is the delta, or the amount of color change you want between LEDs. For instance, if you want each pixel to increment by a hue value of 5 then the first pixel would display a hue value of 0, the next would be 5, then 10, etc. all the way down your strip.

I want the rainbow to display evenly throughout the length of my LED strip so a clever mathematical formula to use is: 255 / NUM_LEDS. In other words, I want to divide the 255 hue values by the number of pixels I have, which is 20. This means that each pixel down the strip will have a hue value of roughly 13 more than the previous pixel. This should evenly distribute the rainbow colors over my strip. Keep in mind that the length of your strip will affect how the rainbow looks. Shorter strips won’t have enough pixels to show as nice a gradient between colors as longer LED strips. Here is a few different ways to play around with the delta parameter for different effects:

 void loop () {
  //Evenly distribute the rainbow
  fill_rainbow (leds, NUM_LEDS, 0, 255 / NUM_LEDS);
  FastLED.show();
  delay(1000);

  //Display only half the rainbow
  fill_rainbow (leds, NUM_LEDS, 0, 255 / NUM_LEDS / 2);
  FastLED.show();
  delay(1000);

  //Display 2 rainbows
  fill_rainbow (leds, NUM_LEDS, 0, 255 / NUM_LEDS * 2);
  FastLED.show();
  delay(1000);
 }

In the first fill_rainbow code block, I use 255 / NUM_LEDS for the delta parameter in order to display one rainbow evenly down my 20-pixel LED strip. In the next fill_rainbow code block, I use 255 / NUM_LEDS / 2 to display only half the rainbow on my LED strip. Then in the final fill_rainbow code block I use 255 / NUM_LEDS * 2 to show two rainbows on the LED strip. These three rainbow effects alternate at one-second intervals using the delay(1000); function.

By changing the starting and delta hue values, you can create different rainbow lighting animations across your whole LED strip. Try changing each value and try numbers from 0 to 255 for both rather than the equations and see what happens.

Here’s a sketch where we start with a rainbow evenly spread across the LED strip and then the starting hue of each pixel increases by 1 every 50ms. This gives the appearance that the rainbow is traveling slowly down the strip. The code in its entirety looks like this:

 #include <FastLED.h>

 #define NUM_LEDS 20
 #define LED_PIN 2

 CRGB leds[NUM_LEDS];

 uint8_t startHue = 0;

 void setup() {
  FastLED.addLeds<WS2812B, LED_PIN, GRB>(leds, NUM_LEDS);
  FastLED.setBrightness(50);
  delay(2000);
 }

 void loop () {

  fill_rainbow (leds, NUM_LEDS, startHue, 255 / NUM_LEDS);
  FastLED.show();
  delay(50);
  startHue++;
 }

Right above the setup () function you’ll see that I declared a variable using a uint8_t type for our starting hue, called it startHue and set it equal to 0. This means that the starting hue of my rainbow is red at the beginning of the animation. You’ll see variables used a lot in lighting animations like byte, uint8_t, uint16_t and others. A uint8_t stores an 8-bit unsigned integer from 0 to 255 which is perfect for cycling through hues since they also use those values.

In the fill_rainbow code block, I put the variable startHue instead of specifying 0 like we’ve done before so its value can be manipulated in the code. The delta stays at 255 / NUM_LEDS so that the rainbow displays evenly along my LED strip. At the end of the sketch, I increase the startHue by 1 before it loops back to the beginning of the program with the new startHue which would now be 1. Changing the starting hue in the fill_rainbow function shifts how the other colors get displayed down the strip. The startHue will continue increasing by 1 every 50ms until the startHue reaches 255 and then loops back to 0. If you want the rainbow to move down the LED strip at a faster or slower pace, simply adjust the time in the delay() function in milliseconds.

In this next example, the sketch is basically the same but we build on what we did with the starting hue. In addition to increasing the startHue, we’re also going to increase the delta of the hue.

 #include <FastLED.h>

 #define NUM_LEDS 20
 #define LED_PIN 2

 CRGB leds[NUM_LEDS];

 uint8_t startHue = 0;
 uint8_t deltaHue = 0;

 void setup() {
  FastLED.addLeds<WS2812B, LED_PIN, GRB>(leds, NUM_LEDS);
  FastLED.setBrightness(50);
  delay(2000);
 }

 void loop () {

  fill_rainbow (leds, NUM_LEDS, startHue, deltaHue);
  FastLED.show();
  delay(50);
  startHue++;
  deltaHue++
 }

Just like the startHue, I also declared a variable for the delta of the hue and called it deltaHue. In the fill_rainbow line of code, I replaced 255 / NUM_LEDS with deltaHue so its value can also be manipulated. At the bottom of the sketch, I not only increase the value of the starting hue by 1 but I also do it for the deltaHue variable. Every time the startHue value increases, it shifts how the colors of the rainbow are displayed along the strip. On top of that, increasing the deltaHue value causes the colors of pixels that are right next to each other to be more and more further apart on the hue color chart shown above. There comes a point where both variables, the startHue and deltaHue, cycle back to 0 and if you watch the animation below very closely you’ll see a quick red flash. Then while the values are still low, the rainbow is a bit more seamless before breaking up as the numbers get larger and larger.

Using variables for some of the parameters in the FastLED functions we’ve used allows you to create some interesting lighting effects.

Advanced Color Control with FastLED

I hope that by now, the FastLED library doesn’t seem as intimidating to learn as before. With just a few functions and over 100 pre-defined colors to choose from, you can now make amazing lighting animations to enhance your project. We also got an initial look at specifying colors using hue values which will be crucial as you advance. But we’re just getting started! In the next FastLED tutorial, we’re going to explore more ways to further control color that will unlock your ability to produce even more complex and jaw-dropping lighting effects.

Some links in this post are to affiliate sites. If you purchase something through them, I may earn a small commission — which costs you nothing! I am very grateful for your support when you use my links to make a purchase.