A naming convention for UI components

One of the most difficult things in software development is: naming things. This includes variables, functions, classes, and of course, components.

To handle this problem accordingly, especially if you work in a team, nothing like a pattern to help us make things more consistent and easier.

In my team, we've created a pattern for helping us naming UI components, we call it CEV. I know, not so pretty, but works for us. 😄

The CEV pattern

CEV stands for Context, Element, and Variant. We call each of these a token of the component's name.

An example of component name with CEV naming convention (Article Card Large, respectively Context, Element and Variant).
An example of component name with CEV naming convention (Article Card Large, respectively Context, Element and Variant).
An example of a component name with the CEV naming convention.

Take a look at each one in detail, and its rules, below.

What is the context which this component belongs to, uses, or respects?

The context can be a type of content that is being instantiated, the name of a parent element or page where this belongs, or anything that helps you understand what is the scope of this component.

This is usually a noun, in singular or plural, and occasionally an adjective ending with ble.

Examples: Post, Posts, Product, Home, Site, Article, Member, Flexible, Collapsable, etc.

What kind of UI element the component is?

The element name should make clear what to expect from this component in the UI.

This is usually a noun in the singular, and occasionally in the plural.

Examples: List, Card, Form, Section, Block, Content, Details, Carousel, Accordion, Hero, etc.

Is this a variation from another component?

The variant (or variation) is optional and should be used when you have multiple components with a similar role, but with different properties.

The name is usually an adjective.

Ex: Small, Large, Highlighted, Featured, Inverted, etc.

Examples

Here is a list of examples using this pattern:

  • ArticleCard
  • ArticleCardSmall
  • ArticlesList
  • ProductDetails
  • MembersCarousel
  • QuestionsAccordion
  • TextBlocksStacked
  • NavigationMenu
  • FlexibleContent
  • PageHeroAdvanced
  • HomeHero

Order

This order was defined to keep files organized from the greater to smaller scope, being the context the greater, and variation the smaller, so ArticleCardSmall and ArticleCardFeatured will be close to each other.

Exceptions and Restrictions

In most cases, you will need the Context and Element name, while the Variant is always optional, but for some specific cases, the Element name may be enough to easily identify the component, so the Context can be omitted.

Some examples are Header, Footer, Sidebar, and a few others.

To a website, for example, these names are quite intuitive.

However, if you prefer to be more restricted about patterns and conventions, you can require that a Context should always be defined, using something like, SiteHeader, AppFooter, ProjectSidebar, etc.

Make your choice and be clear about it.

Use plural for the Context whenever the Element deals with multiple instances of the same Context, for example, ArticlesList, ProductsCarousel, QuestionsAccordion, etc. Otherwise, use singular, like ArticleCard, ProductDetail, QuestionBlock, and so on.

For the Element, use plural when the component contains multiple instances of this element, like TextColumns, IconBlocks, CollapsableSections, etc.

There are cases where you might need to be more specific, and use more words on a token, maybe to keep things more organized in your project.

As an example, imagine a component named ArticleFaqAccordionSmall, where ArticleFaq represents the Context.

The ideal is to consider this invalid and maybe move one of the words to the Variant instead, like FaqAccordionArticle (or a better name). But if this is definitely a need for your project, you can either create a new prefix token (like a Parent Context, or Domain) or let the Variant contain one or more words, as it would have a lighter impact on the identification of the tokens.

Again, you can adapt the convention to fit your needs, but it's always best to keep it consistent.

Conclusion

There are also many other naming patterns and conventions out there, and you should choose what works best for you, your team, and the projects you work with.

Remember,

A component naming pattern should help you make naming components easier and intuitive, for who is naming the component, for who needs to search for it in the project, or for who found it in the code and needs to know what is it about.

There is no one-fits-all solution, each pattern/convention has its own benefits and weakness, so choose the one that you and your team feel more comfortable with.

And good coding! 😉

A software developer from Brazil