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

# Categories

> Dish categories with counts

Return dish category names and counts for your chain, optionally scoped to a single restaurant. Use this to build category navigation in your menu UI (for example, "Breakfast (12)", "Lunch (24)").

## Query

```graphql theme={null}
query SmartMenuCategories {
  categories {
    name
    count
    ordinal
  }
}
```

<Info>
  This query requires an API key scoped to your chain in the `Authorization` header. Optionally include `X-Session-ID` for analytics and personalization; you do not need to pass chain or session in the GraphQL query itself.
</Info>

## Parameters

| Parameter      | Type | Required | Description                                                                                                                                        |
| -------------- | ---- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `restaurantId` | ID   | No       | If provided, categories are aggregated for this restaurant only. If omitted, categories are aggregated for the chain's widget (all widget dishes). |

## Response

```graphql theme={null}
type WidgetCategory {
  name: String!   # Category name
  count: Int!     # Number of dishes in this category
  ordinal: Int!   # 1-based display order after alphabetical sort
}
```

## Example

<CodeGroup>
  ```graphql Query theme={null}
  query {
    categories {
      name
      count
      ordinal
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "categories": [
        { "name": "Specials", "count": 5, "ordinal": 0 },
        { "name": "Appetizers", "count": 12, "ordinal": 1 },
        { "name": "Salads", "count": 8, "ordinal": 2 },
        { "name": "Bowls", "count": 6, "ordinal": 3 },
        { "name": "Entrees", "count": 15, "ordinal": 4 },
        { "name": "Sides", "count": 10, "ordinal": 5 },
        { "name": "Desserts", "count": 4, "ordinal": 6 },
        { "name": "Beverages", "count": 8, "ordinal": 7 }
      ]
    }
  }
  ```
</CodeGroup>

## Filtering by Category

Use the `category` parameter in the search query to filter dishes:

```graphql theme={null}
query SaladDishes {
  search(
    category: "Salads"
    preferences: {
      diets: [VEGETARIAN]
    }
  ) {
    matches {
      dish {
        id
        name
        category
      }
    }
    counts { matches, total }
  }
}
```

## Category Counts with Preferences

<Note>
  Category counts returned by `categories` represent **total dishes**, not dishes matching any preference filters. For filtered counts, use the search query with a category filter.
</Note>

To get counts that respect preferences, query each category:

```graphql theme={null}
query CategoryCounts {
  salads: search(
    category: "Salads"
    preferences: { diets: [VEGETARIAN] }
  ) {
    counts { matches }
  }

  bowls: search(
    category: "Bowls"
    preferences: { diets: [VEGETARIAN] }
  ) {
    counts { matches }
  }
}
```

## Display Recommendations

<CardGroup cols={2}>
  <Card title="Use Ordinal for Order" icon="sort">
    Display categories in `ordinal` order to match the restaurant's intended menu layout.
  </Card>

  <Card title="Show Match Counts" icon="calculator">
    Consider showing "X matches" next to each category when filters are active.
  </Card>

  <Card title="Hide Empty Categories" icon="eye-slash">
    Optionally hide categories with 0 matches when dietary filters are applied.
  </Card>

  <Card title="Sticky Navigation" icon="thumbtack">
    For long menus, consider a sticky category bar for easy navigation.
  </Card>
</CardGroup>