From camelCase to kebab-case: Our naming convention

Unlike other programming languages, toddle does not enforce strict naming. Often you can just use standard English, including spaces and special characters when naming your formulas and workflows.

Flexibility is great, but having conventions helps maintain consistency and efficiency in and across projects. That’s why we established a unified naming convention and are sharing it publicly—to reduce decision fatigue, allowing you to focus on building your amazing toddle project!

Casing Types Explained

Numerous casing types are used in programming. Here is a quick recap on the most commonly used casing types.

• camelCase:
  The first word is lowercase, and subsequent words are capitalized without spaces.
  
  - Examples: myVariable, fetchData, selectedNodeIndex

• PascalCase:
  Similar to camelCase, the first letter is also capitalized.
  
  - Examples: MyComponent, UserProfile, DashboardSidebar

• kebab-case:
  Words are lowercase and separated by hyphens (-).
  
  - Examples: dashboard-sidebar, landing-page-banner, toddle-logo.svg

• snake_case:
  Words are lowercase and separated by underscores ("_").
  
  - Examples: user_profile, get_all_properties, selected_node_index

• Sentence case:
  This is just like writing a normal sentence (also known as "Normal case"). Capitalize the first word. All subsequent words are lowercase with a few exceptions such as proper nouns "Set Marija's variable", "Connect Supabase", etc. We use English language and grammar as we are an international team and it is the only overlapping language between us.
  
  -Examples: Search users, Get all CSS properties, Go to Homepage (as Homepage is a unique noun)

TL;DR

This table is an up-to-date reference on how we name things in toddle. Keep in mind that while this is the naming convention team toddle uses internally to develop toddle in toddle, it is by no means an official naming convention.

The examples are real-life data taken directly from the toddle project. You can use the table above as is or modify to your liking. Please read along for why we decided on the convention above:

1. Pages

We use sentence casing for pages, with the limitation of no special characters as they are not permitted in toddle.

Keep in mind that some page-names have special meaning and logic assigned to them. For example, naming a page "404" will be your go-to for any route that does not match any of your routes.

• Examples
  
  • Blog
  • Blog post
  • 404

2. Components

We use kebab-case for our components. Component naming is special as it does not support special characters or even whitespace. This is a compatibility requirement for a [valid custom element name](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name). Additionally, we try always to prefix our elements with at least one key to ensure unique naming when exported as web components (see note).

• Note on web components
  
  When a toddle component is exported as a web component, its name is used as the custom-element name. However, if the name does not include at least one hyphen(-), the component is prefixed with "toddle-" to be allowed as a custom element by the browser.
  
  This could result in naming collisions, such as between "button" and "toddle-button".

In addition to avoiding collisions (see note above), we find that prefixing often leads to more precise naming. ie. what is a "sidebar" compared to a "dashboard-sidebar" and it avoids name-collision next time you need to make a "sidebar" for your "project" page.

• Examples
  
  • dashboard-sidebar
  • project-sidebar
  • workflow-editor-item

2.1. Component attributes

We similarly use kebab-case for our attributes. This is a requirement built into toddle to be compatible with the custom element spec. You may use reserved keywords such as id, name, class, style, etc. as long as you consider the implications when exported as a web component.

• Examples
  
  • user-name
  • canvas-width
  • id

2.2 Variables

Sentence case.

• Examples
  
  • Show confirm dialog
  • Offset
  • Project id to clone

2.3 APIs

Sentence casing.

• Examples
  
  • Projects
  • User's projects
  • Get Discord topics

2.4 Events

Sentence case with a few additional rules. We strive to use event names similar to the [HTML standard elements](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement#events) but without all lowercase. So "click" is "Click" and "dragover" would be "Drag over" etc. We like to be close to the HTML standard and what those terms usually mean to native web development.

Time dimension is important to keep in mind when naming. Most of our events are in past times, as events are side-effects of DOM events. This means a click event would be called "Clicked" instead of "Click" unless the click event itself is passed.

The abstraction level is important. Often "Clicked" is less precise than "Selected" especially if the event can be triggered by both a click and a keyboard press. Creating components is all about the level of abstraction, so pick your event names carefully.

• Examples
  
  • Click (Passes the actual click event)
  • Clicked (custom event object)
  • Closed
  • Node selected

2.5 Component formulas

We use sentence casing for formulas.

Exception: Formulas holding constants are in all uppercase. A formula constant means that it takes no arguments and that its output does not rely on stateful data such as APIs or variables. It could be a list of hardcoded project IDs ("PROJECT IDS") or a computed, but constant, value ("PI SQUARED" for example).

• Examples
  
  • Selected node index
  • Number to HEX
  • Get all CSS properties
  • WEATHER CHALLENGE PROJECT ID

2.6 Component workflows

Sentence case for both the name and inputs.

• Examples
  
  • Reward achievement
  • Set user status

2.7 Slots

kebab-case. When a toddle component is exported as a web component, you can override slotted content by inserting an element inside with:

• <img slot="my-slot" />
  

While custom elements don't technically limit you in what you call your slots, we prefer to avoid any potential casing issues and special character encoding in HTML and CSS by sticking to kebab-case.

Additionally, we try to use the default slot instead of named slots entirely for content that is strictly the main content of the component. For example, a ui-dialog component may have many slots for overriding various content, the default unnamed slot would be the content area of the dialog.

• Examples
  
  • default (empty)
  • icon
  • loading-text

3. (Global) Formulas

Unlike component formulas, we use camelCase for global formulas. We would use sentence casing, but whitespace and special characters are not currently supported for global formulas due to technical limitations. There are rumors this may change in the future, in which case we will revisit our global formula naming convention to align more closely with component formulas.

Constants, which for global formulas means no arguments and no use of the few non-pure-functions (Random, Now & Get from Local Storage), are in all uppercase.

• Examples
  
  • createObjectURL
  • getIssueMessage
  • CHALLENGES

4. Actions

camelCase. Similar to global formulas, it is currently a requirement for actions not to use any special characters to be compatible with JavaScript function naming. As stated, there is an open issue to remove this limitation in the future, at which point we may update the naming convention here.

We generally don't have many actions. Usually, we only add custom code actions when we need a specific browser API that toddle does not include as part of its core. If the API is likely to benefit other users we usually don't even create the action in our project, but rather create a package with the action and install it into our project to divide responsibility and help the community. If we need it, perhaps others may as well.

Instead of creating a single action to handle a specific use case, we prefer to create multiple that can be used more generically. This means that a good name often matches certain browser APIs. For example, we have a requestAnimationFrame, scrollIntoView, or useWorker which are just thin integration into browser features.

• Examples
  
  • requestIdleCallback
  • scrollIntoView
  • useWorker

4.1 Action arguments

Once again, we follow the JavaScript standard and have arguments written in camelCase. If you were to use white space or special characters, then you would only be able to access your argument in custom code by key args ["My argument"] instead of having the standard accessor args.myArguement or the possibility to destruct the input arguments.

• Examples
  
  • elementId
  • scrollX

4.2 Action events

Same as 2.4 events

• Examples
  
  • Callback
  • Key pressed

5. Media

We use kebab-case for media files as they are consumed with a URL that includes their name, we try to stay away from special characters to avoid having to worry about escaping characters. By forcing lower-casing we also avoid issues when having to weakly type their name.

Additionally, we post-fix with the file extension. This is not a requirement as the file format is encoded into media files, but it allows having multiple formats for the same file to support the <picture> element fallback, etc.

• Examples
  
  • toddle-logo.svg
  • landing-page-banner.webp
  • landing-page-banner.png

#whynamingmatters

While not essential to programming, naming conventions help reduce decision fatigue and create more structured, maintainable projects—especially in team environments. There’s no universal approach, but having a clear standard makes collaboration much smoother. What naming conventions do you follow? Share your thoughts in the toddle Discord!