In Excel VBA, reference a UserForm by its form class name, such as UserForm1, or create an explicit object variable with New UserForm1. To display it, call .Show; to work with its controls or properties, use the form object followed by the control or property name.
What “reference a UserForm” means
A UserForm is a custom dialog or window that belongs to a VBA project. It has a class name, controls such as text boxes and buttons, and code that responds to events. When someone asks how to “reference” a UserForm, they may mean how to show it, how to address it from another procedure, or how to read and change its controls. These are related tasks, but they are not the same as adding a library reference.
For example, if the form’s (Name) property is UserForm1, then UserForm1.Show displays it using VBA’s default instance. Alternatively, code can declare a variable of that form’s type, create an instance, and show that instance. The right choice depends mainly on whether the project needs one simple form or multiple independently managed copies.
Find the form name and its code
In Excel for Microsoft 365 on Windows, open the Visual Basic Editor with Alt+F11. On a Mac, use Option+F11 where available, or open the editor through the Developer tab; keyboard behavior can depend on the keyboard and macOS settings. In Project Explorer, expand the workbook’s VBA project and look under Forms. Double-click a form to open its designer, or right-click it and choose View Code to see its event procedures.
Select the form itself in the designer and inspect the Properties window. Its (Name) property is the identifier used in VBA. This is distinct from the Caption property, which is the text displayed in the form’s title bar. A form might have the name frmCustomer and the caption “Customer details”; code refers to frmCustomer, not to its caption.
Controls have their own names too. For instance, a text box might be named txtCustomer, and a button might be named cmdSave. Those names are what code uses when it reads or changes a control’s value. Renaming a form or control changes the identifier you must use in code, so consistent names make larger projects easier to maintain.
Show a form with its default instance
For a straightforward form used once, calling its name is usually the shortest approach. If the form is named UserForm1, a standard module can contain:
Sub OpenUserForm()
' Display the form's default instance.
UserForm1.Show
End Sub
This is called the default instance: VBA provides an instance associated with the form’s class name when code uses the form that way. It is convenient for a small data-entry dialog, but it can make form state less explicit when a project grows or when more than one copy could be open. For a modal display, which is the default, execution pauses at .Show until the form is hidden or unloaded.
Before running any macro, save a copy of the workbook. VBA macros cannot be undone with Ctrl+Z. Store a workbook containing VBA in a macro-enabled format such as .xlsm; saving it as a macro-free workbook can remove its VBA project.
Create and use an explicit form reference
To make the instance clear, declare a variable using the form’s class name, create it with New, and call its methods through that variable. The following example assumes the form’s (Name) property is UserForm1:
Sub OpenFormWithObjectVariable()
Dim frm As UserForm1
' Create a separate instance of the form.
Set frm = New UserForm1
frm.Show vbModal
End Sub
The variable frm is an object reference, and Set assigns the newly created form instance to it. Writing frm.Show vbModal makes the display mode explicit. When the procedure ends, its local variable goes out of scope. This pattern is useful when another procedure needs to configure the form before showing it or when you want to avoid relying on the default instance.
Creating a fresh instance each time is not the same as reusing a form that has been hidden. A new instance starts with its own controls and state. If a project needs a persistent modeless window or needs to share a particular instance across procedures, the reference must be kept in a scope that remains alive, such as a module-level variable, and its lifetime should be managed deliberately.
Choose modal or modeless display
Show can display a form modally or modelessly. A modal form keeps the user in that dialog until it is dismissed; the calling procedure does not continue past .Show in the meantime. This is often appropriate when a macro needs the user to complete a prompt before it continues.
A modeless form lets the user interact with Excel while the form remains open. Specify vbModeless when showing it. Modeless forms can be useful for tools such as a small search or formatting panel, but they require more thought: the workbook may change while the form is open, and code should not assume that the active sheet or selection is unchanged. Capture a specific workbook, worksheet, or range when the form opens if later actions must target that object reliably.
For example, the explicit-instance example can use frm.Show vbModeless instead of frm.Show vbModal. The choice affects how the user interacts with Excel, not how the form is referenced. It also does not automatically create a second instance; instance creation is controlled by whether code uses the default instance or creates an object with New.
Reference controls and pass information
To access a control, qualify it with the form instance. With a form variable named frm and a text box named txtCustomer, code can read frm.txtCustomer.Value. With the default instance, it can use UserForm1.txtCustomer.Value. Qualifying the control makes clear which form’s value is being read, especially if more than one instance exists.
Often, it is cleaner to keep interaction code in the form’s own event procedures. For example, double-click the Save button in the designer to create its click event, then put the following code in the UserForm’s code module. It assumes the form contains a text box named txtCustomer and the workbook contains a worksheet named Data:
Private Sub cmdSave_Click()
Dim ws As Worksheet
' Write the entered value to the Data sheet.
Set ws = ThisWorkbook.Worksheets("Data")
ws.Range("A1").Value = Me.txtCustomer.Value
' Close this instance of the form.
Unload Me
End Sub
Here, Me means the UserForm instance whose code is running. It avoids hard-coding the form’s name inside its own event code and remains clear if the form is renamed. The example writes to ThisWorkbook, meaning the workbook containing the VBA code, rather than whichever workbook happens to be active. If the sheet name or control name differs, update the identifiers to match the project.
A form can also expose public properties or methods for other procedures to use. That approach can be more maintainable than having outside code reach into several controls directly. For example, a form might provide a public function that returns validated input. For a small form, direct control access is usually understandable; for a larger application, defined properties and methods help separate the interface from the rest of the workbook’s logic.
Hide, unload, and manage the form’s lifetime
Hide makes a form invisible but keeps that instance available, so its current control values can generally be read later if the same instance is retained. This is useful when a form is temporarily dismissed and may be shown again with its entries intact. By contrast, Unload closes the form and unloads its controls. When the form is next loaded, its initialization code runs again, so code should not treat its old control state as a reliable place to store data.
Inside a UserForm procedure, Me.Hide and Unload Me act on the current instance. From another module, use the relevant form reference, such as frm.Hide or frm’s unload operation through the form object. Choose based on what should happen to the form’s state, not just on which command is shorter. If the form is meant to submit data and close, unloading it is a common choice; if it is meant to pause and resume, hiding may fit better.
Keep references and data responsibilities distinct. A form variable identifies an object; it is not a safe substitute for storing important data. Copy user input into worksheet cells or ordinary variables before discarding the form if later code needs it. For multiple instances, avoid referring back to the default instance by name when you actually mean a separately created object, since that could address a different instance.
UserForm references versus Tools > References
The VBA editor also has a Tools > References dialog. This selects external type libraries and object libraries used by a VBA project—for example, a library that lets code use additional objects. It is not normally required just to show a UserForm that is part of the same workbook’s VBA project. The form’s class is already part of that project, so code can declare its form type directly.
A missing-library entry in Tools > References can cause compile errors in a project that depends on that library, but it is a different issue from an incorrectly named UserForm. If VBA highlights a form name as undefined, first check that the form exists in the current project, that its (Name) property matches the code, and that the code is in the intended workbook project. If the error concerns a library, inspect the References dialog separately rather than adding arbitrary references.
Common errors and practical checks
- Using the caption as the identifier: Check the form’s
(Name)property, not the title-bar text inCaption. - Misspelling a control name: Confirm the control’s (Name) property in the designer. A text box named
TextBox1will not respond to code that refers totxtCustomer. - Declaring the wrong type: The declaration must use the form class name, such as
Dim frm As UserForm1, and the creation expression must match it:Set frm = New UserForm1. - Using a form that is not in the current project: In the editor’s Project Explorer, check which workbook project contains the form. A form in another workbook is not automatically a class in the current project.
- Reading a value after unloading: Save the needed value before unloading the form, or use a deliberate method of returning it. Do not assume a closed form’s controls retain usable data.
- Confusing a missing reference with a missing form: Tools > References is for libraries. A UserForm naming or scope problem usually needs a project, identifier, or code-location check instead.
When debugging, put the cursor in a procedure and use the editor’s compile command from the Debug menu to identify compile-time problems. Also verify that code intended to run when a button is clicked is inside that form’s event procedure, not in a standard module under a similar-looking procedure name. Event procedure names must correspond to the control’s name and event, such as cmdSave_Click.
Frequently Asked Questions
How do I call a UserForm from a standard module?
Use its class name and call .Show, for example UserForm1.Show. To create an explicit instance, declare a variable as that form type, assign New UserForm1 with Set, and call frm.Show.
Do I need to add a reference to use a UserForm?
No, not when the UserForm is part of the same VBA project. The Tools > References dialog is for external libraries, not for registering a form contained in the workbook.
What is the difference between UserForm1.Show and New UserForm1?UserForm1.Show uses the form’s default instance. New UserForm1 creates an instance that you can assign to an object variable. The latter makes instance ownership explicit and allows separate instances when the code needs them.
How do I get a value from a UserForm?
While the instance is available, read the relevant control’s value, such as frm.txtCustomer.Value, or expose a public property or method. If you unload the form, first copy any value that must be used afterward.
Should I use Hide or Unload?
Use Hide when you intend to show the same instance again and preserve its current state. Use Unload when the form should be closed and its controls unloaded; save any needed input elsewhere first.
Why does VBA say a UserForm is not defined?
Check that the form is in the active VBA project and that the code uses its exact (Name) property. Also confirm the declaration’s type matches the form class and that you have not confused the form’s displayed Caption with its VBA name.
Related
- table() in RStudio: How It Counts and Displays Data
- Data Validation and Reconciliation in Excel Explained
- PowerPoint Table Diagonal Split Cell: Practical Methods
Try it: the Column Letter to Number: aA is 27, XFD is 16,384. Converts both ways.
More in VBA & macros
- VBA Sort Key: How Key1 and SortFields WorkIn VBA, a sort key is the cell or range that tells Excel which column’s values to use…
- Macro Recorder on Softonic: Download and Safety GuideMacro Recorder is a desktop automation program that records mouse and keyboard actions and plays them back; Softonic…
- Excel VBA Freeze Panes at a Specific CellYes. Activate the worksheet, select the cell that marks the top-left corner of the scrolling area, then set…
- Excel Macro Filter: How to Automate Data FilteringTo filter a worksheet with a macro, use VBA’s AutoFilter method on a range that includes its header…
- VBA Sort Not Working? Fix Excel Sorting Macros with Clear RangesIf VBA sorting is not working, check that the macro is running, the sort range includes every column…
- VBA MsgBox Scroll: Limits and Scrollable AlternativesNo: VBA’s built-in MsgBox has no setting or argument that adds a scrollbar. For long text, use a…
Sources: Function behaviour and menu paths: Microsoft Support documentation for Excel. Method & sources
Spotted an error in this guide? Let us know.