Build your display in xLights

Put your house on screen, add your lights one prop at a time (rooflines, a GE snowflake, a mega tree) and save it. This is the job you do once, before any sequence can play.

Part of the beginner series: 1. Build Your Display · 2. Connect Your Controller · 3. Load Your Sequence

The whole journey at a glance

• 1Make your show folder
• 2A photo of your house
• 3A straight line of pixels
• 4Lines that turn corners
• 5Download a ready-made prop
• 6Set up a mega tree
• 7Make groups, then save
• ?If something isn't right

Menu and button names come from xLights 2026 and can shift a little between versions. If something looks slightly different, look for the same words close by. Pictures on this page are simplified drawings, not exact screenshots.

Have these four things ready

xLights needs to know what lights you have and where they are. That description is your layout. Once it's built, every sequence you make or buy plays on it.

Words you'll see in this guide

The Layout tab

Everything in this guide happens on the Layout tab. It has four parts you'll use all the time.

xLights keeps everything for your display in one folder. Make it once and keep using it every year.

1. In File Explorer (Finder on a Mac), make a new, empty folder somewhere easy to find, for example Documents\xLights Show.
2. Open xLights and go to the Controllers tab. At the top you'll see the current show folder.
3. Click Change Permanently and choose your new folder. From now on xLights opens it every time.

The photo is just a guide to trace over, so your lights sit in the right places. It doesn't change how the show works.

1. Copy your house photo into the show folder.
2. On the Layout tab, click an empty part of the preview so no model is selected. The Properties panel now shows the preview's own settings.
3. Click Background Image, browse to your photo and choose it.
4. Click Save. Your house now appears behind the preview.

Your first model: a straight run, such as the front roofline. The same model works for any straight run: a fence, a gutter, a porch column, a stake.

1. Click the Single Line button (a plain diagonal line).
2. On the photo, click at the end of the roof edge where the data wire comes in, hold the button down, and drag to the other end. Let go.
3. In Properties, type your numbers:

1. Check the green square is at the end where your wire really comes in. If it's backwards, right-click the line and choose Swap Start/End.
2. Repeat for each straight run on the house.

A peaked roof, a garage door outline, a window frame: one string of pixels that bends. Use a Poly Line so it stays one model, just like the real wire.

1. Click the Poly Line button (a zig-zag line).
2. Click where the data wire comes in, hold and drag to the first corner, then click once.
3. Move to the next corner and click once again. Keep going around the shape.
4. At the last point, click, then press the Esc key to finish drawing.
5. In Properties, set # Nodes to the total pixels in the whole run, and the name and Starting Location as before.

Store-bought props, like a GE snowflake from Gilbert Engineering, have their pixels in a special pattern. Don't draw them yourself: the maker publishes the exact model, and xLights downloads it for you.

1. Click the Download Model button (the downward arrow among the model buttons).
2. On the house photo, click, hold and drag a box where the prop stands. Let go.
3. The download window opens. Open Gilbert Engineering USA → SnowFlakes and pick the size that matches yours (the box or receipt says, e.g. 24").
4. Choose the exact model, check its picture matches your prop, and click Insert.
5. Give it a clear name, such as Snowflake Left.

Models are provided by the vendors, not by xLights. They're free to use in your layout. If a model is wrong or missing, contact the prop's maker.

A mega tree is strands of pixels running from a top ring down to the ground in a cone. xLights has a Tree model for it; you just describe how it's wired.

1. Click the Tree button and drag a box over where the tree stands.
2. In Properties, set the tree's shape and wiring:

A group lets one effect sweep across several models at once, like a chase that runs along every roofline. Most purchased sequences put their effects on groups, so a few good groups make every sequence easier to use.

Make a group

1. Right-click in the Models list and choose Add New Group.
2. Type a name, for example GRP_RoofLine, and click OK.
3. With the group selected, move models from the left list into Models in Group using the arrow buttons.

Shortcut: select several models on the house preview, right-click and choose Create Group.

Save your layout

1. Click Save on the Layout tab. Do it often: xLights reminds you "Layout has unsaved changes" if you forget.
2. Happy with where everything sits? Select all your models, right-click and choose Lock Models so a stray click can't nudge them.

If something isn't right