> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.ttr.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Categories

> Organizing transactions with categories

## Overview

**Categories** help you organize transactions and understand your spending patterns. Each category has a type (income or expense) and optional visual styling.

## Category Properties

| Property     | Type       | Description                            |
| ------------ | ---------- | -------------------------------------- |
| `id`         | String     | Local UUID (primary key)               |
| `serverId`   | String?    | Server-assigned ID after sync          |
| `name`       | String     | Category name (e.g., "Food", "Salary") |
| `type`       | String     | Either `income` or `expense`           |
| `color`      | int?       | Color value for UI (ARGB format)       |
| `icon`       | String?    | Icon identifier (Flutter icon name)    |
| `syncStatus` | SyncStatus | Current sync state                     |

## Creating Categories

### Using the Cache Manager

```dart theme={null}
final cache = CacheManager.instance;

// Expense category
final foodCategory = await cache.createCategory(
  name: 'Food & Dining',
  type: 'expense',
  color: 0xFFFF5722,  // Orange
  icon: 'restaurant',
);

// Income category
final salaryCategory = await cache.createCategory(
  name: 'Salary',
  type: 'income',
  color: 0xFF4CAF50,  // Green
  icon: 'attach_money',
);
```

### Direct Repository Access

```dart theme={null}
final category = Category(
  id: cache.generateId(),
  name: 'Transportation',
  type: 'expense',
  color: 0xFF2196F3,  // Blue
  icon: 'directions_car',
  createdAt: DateTime.now(),
  updatedAt: DateTime.now(),
);

await cache.categories.save(category);
```

## Querying Categories

### Get All Categories

```dart theme={null}
final allCategories = await cache.categories.findAll();
```

### Filter by Type

```dart theme={null}
// Get only expense categories
final expenseCategories = await cache.categories.findByType('expense');

// Get only income categories
final incomeCategories = await cache.categories.findByType('income');
```

### Find by ID

```dart theme={null}
final category = await cache.categories.findById('category-uuid');
```

## Common Category Examples

### Expense Categories

* 🍔 Food & Dining
* 🚗 Transportation
* 🏠 Housing
* 💡 Utilities
* 🎬 Entertainment
* 🛒 Shopping
* 🏥 Healthcare

### Income Categories

* 💼 Salary
* 🎁 Gifts
* 📈 Investments
* 🏠 Rental Income
* 💰 Other Income

## Color Format

Colors are stored as 32-bit ARGB integers:

```dart theme={null}
// Format: 0xAARRGGBB
final red = 0xFFFF0000;      // Red
final green = 0xFF00FF00;    // Green
final blue = 0xFF0000FF;     // Blue

// In Flutter, you can use:
final color = Color(0xFFFF5722);
```

## Updating Categories

```dart theme={null}
final category = await cache.categories.findById(categoryId);
if (category != null) {
  final updated = category.copyWith(
    name: 'Updated Name',
    color: 0xFF9C27B0,  // Change to purple
  );
  await cache.categories.save(updated);
}
```

## Deleting Categories

```dart theme={null}
// Soft delete (recommended)
await cache.categories.delete(categoryId);

// Hard delete
await cache.categories.delete(categoryId, hardDelete: true);
```

<Note>
  When you delete a category, existing transactions will have their `categoryId` set to null (via `ON DELETE SET NULL` constraint).
</Note>

## Best Practices

1. **Keep it simple** - Start with 5-10 categories
2. **Be consistent** - Use the same categories month-to-month
3. **Use colors** - Visual cues help identify categories quickly
4. **Review regularly** - Merge or split categories as needed

## Related

* [Wallets](/concepts/wallets) - Where transactions occur
* [Transactions](/concepts/transactions) - Categorized records