Suggest an edit

Improve this article

Refine the answer for “The Colocation principle in component architecture”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

## What "Colocation" is

> **Colocation** is a principle stating that **code that is logically related should physically live near each other**.

In simpler terms:

> "Keep things together if they belong together."

---

## The meaning of the principle

When a component or function uses some data, styles, hooks, or tests, all of it **should be kept near it**, instead of being scattered across the project's folders.

This increases **the locality of changes**:
you always see everything related to a component without running around the project.

---

## Example without colocation (a bad approach)

```javascript
src/
  components/
    UserCard.jsx
  hooks/
    useUserData.js
  styles/
    userCard.css
  tests/
    UserCard.test.js
```

To change `UserCard`, you have to run across 4 folders.
Everything related to this component is **scattered**.

---

## Example with colocation (the right approach)

```javascript
src/
  components/
    user-card/
      UserCard.jsx
      useUserData.js
      userCard.css
      UserCard.test.js
```

Everything related to `UserCard` is now **in one folder**.
If you delete the component, you delete everything that belongs to it too.
If you change it, you immediately see the context.

---

## An example at the Feature-Sliced Design (FSD) level

```javascript
features/
  add-to-cart/
    ui/
      AddToCartButton.tsx
    model/
      store.ts
      selectors.ts
    lib/
      formatPrice.ts
```

Here colocation happens **inside the feature**:
the UI, logic, and utilities of this feature are stored **together**, instead of in shared `components/`, `store/`, `utils/` folders.

---

## The goal of colocation

1. **Localize context** - everything needed to understand a module is nearby.
2. **Increase modularity** - the feature is self-contained and portable.
3. **Simplify refactoring** - you change one feature without touching others.
4. **Speed up development** - you navigate the code faster.

---

## Where colocation is applied

| Data type | What is best to colocate |
| --- | --- |
| Component | Styles, tests, hooks, types |
| Feature | UI, model, API, helpers |
| Hook | Local utilities and types |
| Entity | UI, model, API of that entity |
| Page | All of its subcomponents and loading logic |

---

## Examples of colocation in React

### Local styles

Instead of `styles/`:

```javascript
// UserCard.jsx
import './UserCard.css';
```

### A local hook

```javascript
// inside /user-card/useUserData.js
export function useUserData(id) {
  const [user, setUser] = useState();
  // ...
  return user;
}
```

### A local test

```javascript
/user-card/UserCard.test.jsx
```

### A local utility

```javascript
/user-card/formatDate.js
```

---

## The "move inward" rule

When code is used in only one place -

> move it closer to where it is used.

When it starts being used in several places -

> extract it upward (for example, from a `feature` into `shared`).

This is a natural, "bottom-up" process of architectural growth.

---

## Summary

| Principle | Description |
| --- | --- |
| What it is | Place related parts of the system near each other |
| Goal | Improve readability, isolate features, simplify maintenance |
| Example | A component + its styles + its tests in one folder |
| Where it applies | Components, hooks, features, pages |
| Result | Minimum chaos, maximum context and convenience |

---

**The main idea:**
"Colocation is about not having to search the whole project for
something that logically belongs to one place."

Markdown · drag & drop images · ⌘B / ⌘I shortcuts536 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.