A custom-coded widget can be added to Streamlabs Desktop either as its native Custom Widget source or as a Browser Source. Use the native source when the widget belongs to the active widget theme; use a Browser Source when you need a widget from another theme, more than one Custom Widget, or a workaround for a source that will not load.
The practical job is not just inserting a source. You also need to know where its code and fields are edited, which theme is active, and how to check the widget in the scene before you rely on it. The steps below follow Streamlabs’ documented options; labels can differ if your installed Desktop version has a different interface.
Choose the source that fits the widget
Streamlabs supports both routes. The native Custom Widget source is the direct route for the Custom Widget associated with the active widget theme. A Browser Source instead loads a widget using its URL, which lets you select a widget from a particular theme without relying on that theme being active as the native source.
| Situation | Better starting point | What to keep in mind |
|---|---|---|
| One Custom Widget in the active theme | Native Custom Widget | The active theme determines which Custom Widget the native source uses. |
| Several Custom Widgets in the scene | Browser Source for each widget | Copy the URL for each intended widget and set its dimensions in Desktop. |
| A widget belongs to an inactive theme | Browser Source | Get the URL for that theme’s Custom Widget. |
| Native source continually loads | Try the documented Browser Source workaround | Streamlabs Support documented this for a reported macOS case; it is not evidence of a general current fault. |
| You want to edit fields or test options | Streamlabs dashboard | Streamlabs recommends dashboard editing for clearer access to fields, testing options and theme switching. |
If your stream has a single chat or alert-style custom element, begin with the native source and confirm that its theme is active. If you are composing a scene with two separately coded widgets, the Browser Source route makes the theme choice explicit for each one. Streamlabs’ guide to getting started with Custom Widgets covers both adding and editing them.
A widget source is separate from the software that carries your broadcast to YouTube. If your wider aim is a computer-operated 24/7 channel, the OBS setup for a 24/7 YouTube stream on an M2 Mac mini explains a different part of that workflow. For this task, concentrate on getting the widget correct in the scene first.
Add the native Custom Widget source
In Streamlabs Desktop, go to the Sources panel for the scene where you want the widget. Click the + icon, scroll to Widgets, select Custom Widget, and choose Add Source. Give the source a recognisable name in the dialog, such as “Custom lower-third” or “Study timer”, then add it.
Naming matters when a scene later contains several layers with similar previews. A descriptive source name helps you locate the widget for editing or hide it while testing without confusing it with a camera, image, or other source. The name is just a label in your scene; it does not change the code or how a widget works.
After adding the source, open its settings. The settings window exposes Browser Settings and the Custom Code area. You do not need to change browser options just because they are present. First establish that you have the intended widget and theme; adjust display dimensions or other available settings only when the preview shows a concrete need.
If the native source does not show the Custom Widget you expected, check the active widget theme before rewriting code. Streamlabs’ widget themes guide explains the relationship between themes and the widget available to the native source. That distinction can save you from editing one widget while Desktop is displaying another.
Open and edit Custom Code
In the Custom Widget source settings, expand Custom Code and choose Edit Custom Code. Streamlabs exposes Custom Fields, HTML, CSS, and JavaScript there. The custom fields are useful for values you may want to change without hunting through the code, while the HTML describes the content and CSS controls its presentation; JavaScript can provide behaviour when the widget requires it.
Treat those areas as related parts of one widget rather than assuming every widget uses all of them. A simple text display may need very little code. A widget someone else supplied may depend on particular field names or expected markup, so changing those casually can break the display. Make a copy of the original code before changing it, and alter one part at a time so you can identify which change caused a problem.
Streamlabs warns that custom code has inherent risks and advises care with code you did not write. That is a practical security point as well as a reliability point: code can do more than render text, and a snippet from an unknown source may not behave as its description suggests. Use code you understand or trust, remove anything you cannot explain, and do not paste account credentials or stream keys into widget code.
The Streamlabs guide also notes that its team cannot advise users on creating their individual widgets. Plan to test your own code and consult its author or documentation when a widget has custom requirements. You can still use the documented editor to place code, but the editor does not make unrelated snippets compatible with one another.
Use the dashboard when editing is easier there
Streamlabs documents two ways to access a Custom Widget: from Desktop or from the dashboard. It recommends editing through the dashboard because custom fields are easier to see, there are more testing options, and switching themes is easier. This is especially useful when you have several fields or are trying to work out whether a problem is in the widget data or its appearance.
Open the Custom Widget page in your authenticated Streamlabs dashboard; this is not an account-free code editor. Choose the widget and theme you intend to work on, make a small change, and use the available testing controls to inspect the result. Return to Desktop and verify that the scene is using the same intended theme or the correct URL-backed widget.
A widget theme groups widget settings, including its Custom Widget. The active theme determines which Custom Widget appears through the native Desktop source. If you need to make another custom widget, Streamlabs’ documented approach is to create another widget theme, make it active while editing that widget, and repeat as needed. Before you go live, switch back to the theme that should provide the native widget, if that is the route you use.
For a channel built around a repeating video playlist, a visual widget is only one scene element among several. The guide to streaming a folder of videos to YouTube Live with Windows and OBS is useful for understanding that separate playback workflow; it does not change how the Custom Widget source itself is selected or edited.
Add a Browser Source when you need a URL
Use a Browser Source when you need several Custom Widgets, a widget tied to an inactive theme, or a URL-based fallback for a native source that is not displaying. On Streamlabs’ Widget Themes page, locate the intended theme and use the link control beside it. Find Custom Widget and copy its URL. In Desktop, click + in Sources, choose Browser Source, add it, and paste the URL into the source settings.
Set the Browser Source width and height to fit the widget you are adding. A very short or narrow browser area can clip content, while an unnecessarily large area can cover more of the scene than expected or make positioning awkward. The correct dimensions depend on the content your code renders; there is no single size that fits every custom widget.
Give each Browser Source a clear name that identifies both its content and, if relevant, its theme. For example, if you add two custom-coded elements from separate themes, names that distinguish them make it easier to hide, resize or edit the right source later. Check the URL carefully when duplicating a source: a copied Browser Source can still point to the original widget until you replace its URL.
This route is not a claim that every widget needs a Browser Source. For a single widget in the active theme, the native Custom Widget is a supported direct route. The URL method gives you a choice of theme and separate sources; choose it for that control or as a documented fallback, not out of habit.
Adjust browser settings with a purpose
The native source has a Browser Settings section, and a Browser Source has settings of its own. Start with the code and source dimensions that correspond to your widget. Change only settings that are available in your installed version and relevant to an observed issue; do not assume a toggle exists just because a guide for another application mentions it.
When a widget looks clipped, compare its rendered content with the source’s width and height, then resize the source and inspect the scene again. If text or an animation appears in the wrong place, look at the widget’s CSS and the scene’s crop or position before changing unrelated browser options. Keep a note of the original values so a change can be reversed.
If the source is blank, changing dimensions may not address the cause. Check that the code is present in the intended widget, that the URL belongs to the intended theme, and that the theme or source route matches your goal. A wrong theme or URL can produce a technically valid source that is not the widget you meant to show.
Test the widget in the scene
Test in the actual scene where the widget will appear, not only in the code editor. Confirm that the right source is visible, that its content fits the canvas, and that it does not sit behind an opaque image or video layer. If it has changing text or a test state, use the dashboard’s available testing options and then check that the change is visible in Desktop.
For a scene with several elements, temporarily hide nearby sources if you cannot tell whether the widget is rendering beneath them. Restore those sources after the check. Move or resize the widget using the scene preview, and watch the edges of the canvas as well as the widget itself; something that looks correct in a settings preview can still be positioned off-screen in the full scene.
Do a final check after switching themes or replacing a URL. The native source follows the active widget theme, while a Browser Source uses the URL you supplied. That means the two routes can show different widgets even when both sources are named “Custom Widget”. Confirm which route you chose and inspect the visible result before relying on it during a live broadcast.
A widget is part of a larger live scene, not a guarantee that the broadcast itself will remain connected. If your stream disconnects after a provider changes your public IP, the Indian ISP RTMP disconnect troubleshooting guide addresses that separate problem. Keep scene testing and connection troubleshooting as distinct checks.
Troubleshoot display issues
If the native Custom Widget is missing or appears to be the wrong one, verify which widget theme is active. The native source is tied to the active theme, so switching themes can change the widget it supplies. If you intended to display a widget from another theme, copy that theme’s Custom Widget URL and add it as a Browser Source instead.
If the widget is present but blank or incomplete, check the Custom Fields, HTML, CSS and JavaScript against the widget’s requirements. Restore the saved original if a recent edit coincides with the problem, then reapply changes in smaller steps. Check for text colour matching the background, content clipped by dimensions, a hidden source, or another layer obscuring the widget before assuming the code itself is at fault.
Streamlabs Support has a documented macOS case in which a natively added Custom Widget continually loads. The article, dated 25 April 2025, lists a workaround: edit the widget in the dashboard, copy its URL, then add that URL in Desktop as a Browser Source. Treat this as a reported case and available troubleshooting path, not proof that all macOS installations have the issue. See the Streamlabs Support article for its specific guidance.
If the menu names do not match, use Streamlabs’ current instructions and the labels in your installed version rather than forcing a step that is not present. The official Custom Widget guide documents the source and code-editor sequence. Streamlabs’ own support guide is another primary reference; check current official help when Desktop’s interface differs.
When the widget and the rest of the channel are ready, decide how you want the continuous broadcast to run.
Before committing, compare the operating options on the pricing page. When the file and channel are ready, start free — 24-hour trial, no card.
FAQ
Should I use Custom Widget or Browser Source?
Use the native Custom Widget source for the widget in the active theme when you need one direct source. Use a Browser Source for multiple Custom Widgets, an inactive theme’s widget, or the documented loading workaround. Both are supported routes; the widget and theme you need determine the choice.
Can I add more than one Custom Widget?
Yes. Streamlabs’ documented method for multiple Custom Widgets is to copy each widget’s URL from its theme and add each as a Browser Source. Give the sources distinct names and set dimensions to suit the content each one displays.
Where should I edit custom fields and code?
You can edit Custom Code in Desktop by opening the source settings, expanding Custom Code, and choosing Edit Custom Code. Streamlabs recommends the dashboard for editing because fields, testing options and theme switching are easier to work with there. Use the authenticated dashboard page for your Custom Widget.
What should I do if the native widget keeps loading?
First confirm the widget and active theme, then consult current Streamlabs help for your version. Streamlabs Support documented a Browser Source workaround for a reported macOS loading case: copy the widget URL from the dashboard and add it in Desktop as a Browser Source. That report is a troubleshooting option, not a guarantee that the same cause applies to your setup.