At some point in pretty much every project, whether you’re setting up the infrastructure or introducing an important library that will be used throughout your app, you run into a tiny problem that turns out not to be so tiny: naming conventions.
Let’s take a classic example.
You need a <Modal />.
Your UI library already has a <Modal />.
So you open a file and write the imports, and suddenly you’re staring at something like this:
import { Modal } from "@heroui/react";
import { Modal } from "./my-components/Modal";You see? You’re not the only one thinking Modal is a great name for a component about… well, a modal! In my case, I liked the name, but the developers building the HeroUI library also liked it.
Now you have a small issue: how are you going to denote that a modal is one of yours, or that it’s imported from your UI library?
In this example you’re probably thinking, “Well, maybe I’ll just rename one.” Obviously. Maybe <HeroModal />. Maybe <MyModal />. It works, JavaScript has no issues, TypeScript stops complaining, and you move on.
The problem with this approach is that your code may start feeling noisy after a while. Not broken, but slightly uncomfortable. You might see different files using different aliases, which isn’t the best approach. This increases your cognitive load because you have to remember things instead of intuitively understanding them.
That’s usually when people think the issue is naming.
It’s not.
What’s actually happening is that two completely different ideas are being treated like they’re the same thing.
A library modal is just a tool. It renders a dialog, handles focus, animates, and gets out of the way.
A modal in your app has meaning. It shows up for specific reasons. It follows product rules. It has opinions.
Once you see that difference, naming stops being a guessing game.
To avoid all this headache, the best thing you can do is stop for a bit, think about your approach, and decide what naming convention—a pattern, if you’d like—will help you intuitively understand what’s going on in your app without having to scroll up to your imports every time you see a component used.
Naming convention 1: Your app owns “Modal”, the library is the “Base”
This is the easiest convention, the one you probably thought about first. The idea behind this is:
- Your app gets to use the “clean” name Modal
- The UI library gets a more technincal name: ModalBase
Example
import { Modal as ModalBase } from "@heroui/react";Then inside your component’s implementation would be:
function Modal(props) {
return <ModalBase {...props} />;
}Other examples for naming your components using this convention could be
<ModalBase />
<BaseModal />
<HeroModal /> // (library-prefixed)
<ModalCore />
<UIModal />
<ModalRaw />
<RawModal />Pros
- ✅ Everyone on your team can use
<Modal />without worrying about where it came from. - ✅ If you ever change your UI library, you only change this wrapper, not your whole codebase.
- ✅ Great for beginners because it keeps things simple and consistent.
Cons
- ❌ If your wrapper grows too much, it can become “magic”. Teammates may not be able to understand why the modal has more complex logic implementation
- ❌ You must be disciplined with naming
Naming convention 2: Name your modals based on what they actually do
In this case you skip the generic name and instead name your modals based on what they are doing. This is helpful for large codebases, not small side projects.
Examples of that could be:
<EditProfileModal />
<DeleteAccountModal />
<InviteUserModal />
<SettingsModal />
<ShareModal />
<ConfirmActionModal />
<FeedbackModal />Pros
- ✅ Very clear meaning – you know what
<DeleteAccountModal />does just by reading it. - ✅ Great for beginners – easier to understand than a generic
<Modal />everywhere.
Cons
- ❌ Can repeat logic – if all modals need the same props or behavior, you might duplicate code.
- ❌ Too many similar names – if you have lots of modals, the list can get long and harder to scan.
Naming convention 3: Use prefix or suffix to show ownership
If the word Modal confuses you because you are not sure where it came from, which is a valid point, you could ignore using the word Modal by itself and instead decide on a good suffix/prefix identifier.
For your UI library component:
<AppModal />
<ProjectModal />
<MainModal />
<CoreModal />
<ClientModal />
<CustomModal />
<ETModal /> // Prefixing your modal with your app's initials e.g Energy Tracker appFor your App component:
<HeroModal />
<LibModal />
<UIModal />
<ModalLib />Pros
- ✅ Very explicit – you can tell at a glance which modal is from your app vs the library.
- ✅ Works well in mixed environments – e.g. multiple UI libraries, monorepos, shared packages.
Cons
- ❌ Names get longer –
<AppModal />,<HeroModal />are not as clean as<Modal />. - ❌ Can become inconsistent – if people invent new prefixes (
<BaseModal />,<CoreModal />,<MainModal />) without a rule.
Naming conventions that usually cause trouble
Most teams try at least one of these at some point.
MyModal sounds harmless but doesn’t mean anything to anyone else.
CustomModal stops being descriptive the moment you have more than one.
Library-branded names everywhere tie your feature code to a vendor, even when it shouldn’t care.
Versioned names like Modal2 or NewModal are usually a sign that a decision was postponed, not solved.
All of them work… until they don’t.
A simple question that keeps things clean
When naming feels hard, this question usually cuts through the noise:
Is this a basic UI building block, or does it express actual product behavior?
If it’s a tool, name it like one.
Example: <ModalBase />, <InputPrimitive />, <ButtonCore />.
If it’s intent, name it like intent.
Example: <EditProfileModal />, <CreateProjectForm />, <DeleteAccountModal />.
That’s the whole trick. You’ll know you’ve landed in a good place when your imports start feeling calm again:
Wrapping up
Naming might look like a small detail, but it affects how your whole project feels. Usually when I’m building a project and it’s time to decide on a UI library, I don’t want to spend time trying to identify names — I just start using whatever the import gives me and continue.
The problem is that after a while I usually find myself needing to refactor because my app is getting more complex. You might say, “Well, it’s fine, you’re following the simple-now, refactor-later idea,” and you might be right. There’s a principle in programming, called YAGNI, that says you shouldn’t build complex systems just in case. You build infrastructure when you know you will need it soon.
This applies directly to naming conventions.
If you’re building a small side project just for fun, go ahead and use the UI library names like <Modal /> and skip the wrappers.
But if you’re building an app you plan to present, monetize, or seriously grow, then stop for a moment, decide on your conventions, and then continue. The time you spend choosing now will be far less than the time you’ll lose later dealing with refactors and headaches.
If you’re just getting started with app development, naming conventions are one of those topics that only start to matter after your environment is properly set up. If you’re still at that stage, you might find these guides useful before diving deeper into UI architecture:
– How to install Git on macOS
– How to install Homebrew on macOS
– How to install npm on macOS
– How to install PostgreSQL on macOS
– How to install Java on macOS
