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

# Flutter

> Add Argide to your Flutter app

The `argide_flutter` package adds Argide to any Flutter app. Use `ArgideWidget` for a floating chat button that overlays your existing app, drop in `ArgideChatView` for a full-screen chat experience.

## Installation

```bash theme={null}
flutter pub add argide_flutter
```

## Quick Start

### Floating Widget (Recommended)

Add `ArgideWidget` inside a `Stack` to get a floating chat button that slides up a chat sheet — zero extra UI work:

```dart theme={null}
import 'package:argide_flutter/argide_flutter.dart';
import 'package:flutter/material.dart';

void main() => runApp(
  const ArgideScope(
    productId: 'YOUR_PRODUCT_ID',
    apiUrl:'https://dashboard.argide.ai',
    child: MyApp(),
  ),
);

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      // builder wraps every route — ArgideWidget appears on all pages
      builder: (context, child) => Stack(
        children: [child!, const ArgideWidget()],
      ),
      home: const HomeScreen(),
    );
  }
}
```

<Note>
  Placing `ArgideWidget` in `MaterialApp.builder` means it automatically appears on every page and route in your app — no need to add it to each screen individually. Tapping the button slides up a chat sheet at 85% screen height.
</Note>

### Full-Screen Chat

Wrap your app with `ArgideScope` and drop in `ArgideChatView` as the full body:

```dart theme={null}
import 'package:argide_flutter/argide_flutter.dart';
import 'package:flutter/material.dart';

void main() => runApp(
  const ArgideScope(
    productId: 'YOUR_PRODUCT_ID',
    child: MyApp(),
  ),
);

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: Scaffold(body: ArgideChatView()),
    );
  }
}
```

`ArgideChatView` includes message bubbles, streaming, conversation history, suggested actions, and a "Powered by Argide" footer — no additional setup required.

## ArgideScope Props

`ArgideScope` is an `InheritedWidget` that provides the client and state down the widget tree.

| Prop            | Required | Description                        |
| --------------- | -------- | ---------------------------------- |
| `productId`     | Yes      | Your product ID from the dashboard |
| `apiUrl`        | Yes      | API URL                            |
| `identityToken` | No       | JWT token for authenticated users  |

## ArgideWidget Props

| Prop    | Required | Description                                                   |
| ------- | -------- | ------------------------------------------------------------- |
| `theme` | No       | `ArgideTheme` instance to customize the chat sheet appearance |

## ArgideChatView Props

| Prop    | Required | Description                                    |
| ------- | -------- | ---------------------------------------------- |
| `theme` | No       | `ArgideTheme` instance to customize appearance |

## Theming

Customize colors and styles via `ArgideTheme`:

```dart theme={null}
ArgideChatView(
  theme: ArgideTheme(
    backgroundColor: Colors.white,
    userBubbleColor: Colors.white,
    userBubbleTextColor: const Color(0xFF111827),
    assistantBubbleColor: Colors.black,
    assistantBubbleTextColor: Colors.white,
    inputBorderColor: const Color(0xFFE5E7EB),
    sendButtonColor: Colors.black,
    bubbleBorderRadius: 18.0,
    poweredByColor: const Color(0xFF9CA3AF),
  ),
)
```

### Theme Properties

| Property                   | Description                                |
| -------------------------- | ------------------------------------------ |
| `backgroundColor`          | Chat background color                      |
| `userBubbleColor`          | User message bubble background             |
| `userBubbleTextColor`      | User message text color                    |
| `assistantBubbleColor`     | Assistant bubble background                |
| `assistantBubbleTextColor` | Assistant message text color               |
| `sendButtonColor`          | Send button color                          |
| `bubbleBorderRadius`       | Corner radius for message bubbles          |
| `inputBorderColor`         | Input bar border color                     |
| `inputBorderLoadingColor`  | Input border color while streaming         |
| `poweredByColor`           | "Powered by Argide" text color             |
| `headerBorderColor`        | Bottom border of the header                |
| `messageTextStyle`         | Full `TextStyle` override for message text |

## User Identity

Identify users to enable conversation history and personalized responses:

```dart theme={null}
final notifier = ArgideScope.chatOf(context);

// From a login handler
final token = await fetchTokenFromYourBackend();
notifier.identify(IdentifyOptions(token: token));

// Or pass via ArgideScope props (auto-updates when token changes)
ArgideScope(
  productId: 'YOUR_PRODUCT_ID',
  identityToken: userToken,
  child: MyApp(),
)

// Logout
notifier.resetUser();
```

See [Identity Verification](/setup/identity-verification) for generating tokens on your backend.

## Client-Side Tools

Register tools that run natively in your Flutter app:

```dart theme={null}
final notifier = ArgideScope.chatOf(context);

notifier.registerTools({
  'navigateToScreen': (params) async {
    final screen = params['screen'] as String;
    Navigator.pushNamed(context, '/$screen');
    return {'navigated_to': screen};
  },
  'addToCart': (params) async {
    final productId = params['product_id'] as String;
    await cartController.add(productId);
    return {'added': productId};
  },
});
```

Upload tool definitions on the [Actions](/agent/actions) page so the agent knows when to call them.

## Platform Support

| Platform | Support |
| -------- | ------- |
| iOS      | ✅       |
| Android  | ✅       |
| macOS    | ✅       |
| Web      | ✅       |

### iOS / macOS

No additional configuration needed. For macOS apps, add the outbound networking entitlement — required for all network calls, including production:

```xml theme={null}
<!-- macos/Runner/DebugProfile.entitlements -->
<key>com.apple.security.network.client</key>
<true/>
```

## Differences from Other SDKs

| Feature    | Web (`@argide/ui`) | React Native         | Flutter                      |
| ---------- | ------------------ | -------------------- | ---------------------------- |
| Language   | TypeScript         | TypeScript           | Dart                         |
| Drop-in UI | `<ArgideWidget />` | `<ArgideWidget />`   | `ArgideWidget`               |
| State      | `useChat()` hook   | `useChat()` hook     | `ArgideChatNotifier`         |
| Storage    | localStorage       | AsyncStorage adapter | SharedPreferences (built-in) |
| Provider   | `<ArgideProvider>` | `<ArgideProvider>`   | `ArgideScope`                |

<CardGroup cols={2}>
  <Card title="Identity Verification" icon="shield-halved" href="/setup/identity-verification">
    Generate JWT tokens on your backend
  </Card>

  <Card title="Client-Side Tools" icon="wrench" href="/integration/client-side-tools">
    Register tools the agent can call
  </Card>

  <Card title="Embed Widget" icon="code" href="/setup/embed-widget">
    Web widget installation guide
  </Card>
</CardGroup>