Widgets & Components

Google Chat Cards feature a comprehensive set of layout widgets and interactive components.

DecoratedText (Replaces Legacy KeyValue)

DecoratedText displays structured data rows with optional top/bottom labels, start/end icons, click-through URLs, or inline action buttons.

use NotificationChannels\GoogleChat\Widgets\DecoratedText;
use NotificationChannels\GoogleChat\Components\Button;
use NotificationChannels\GoogleChat\Enums\Icon;

// Basic Decorated Text
DecoratedText::create('John Doe')
    ->topLabel('Assigned Engineer')
    ->startIcon(Icon::PERSON);

// Decorated Text with Click Action & Button
DecoratedText::create('https://github.com/eighteen73/laravel-google-chat')
    ->topLabel('Repository')
    ->bottomLabel('Open Source Package')
    ->startIcon(Icon::BOOKMARK)
    ->openUrl('https://github.com/eighteen73/laravel-google-chat')
    ->button(
        Button::text('View Code')->openUrl('https://github.com/eighteen73/laravel-google-chat')
    );

Icon Options

Icons can use the strict NotificationChannels\GoogleChat\Enums\Icon backed enum, a custom HTTPS image URL, or a Google Material icon:

// Using Icon Enum
$decoratedText->startIcon(Icon::TRAIN);

// Using Custom HTTPS Image URL
$decoratedText->startIcon('https://cdn.example.com/custom-icon.png');

// Using a Google Material icon
use NotificationChannels\GoogleChat\Components\MaterialIcon;

$decoratedText->startIcon(
    MaterialIcon::make('settings')->fill()->weight(500)->grade(200)
);

Material icon names are available from Google Fonts. Google Chat supports optional filled paths, weights from 100 to 700 in increments of 100, and grades of -25, 0, or 200.

ButtonList & Button

ButtonList arranges one or more Button components horizontally inside a card section.

use NotificationChannels\GoogleChat\Widgets\ButtonList;
use NotificationChannels\GoogleChat\Components\Button;
use NotificationChannels\GoogleChat\Enums\Icon;

ButtonList::create([
    Button::text('Approve')
        ->icon(Icon::CHECK)
        ->openUrl('https://app.example.com/orders/1048/approve'),

    Button::text('Reject')
        ->icon(Icon::CLOSE)
        ->disabled(false)
        ->openUrl('https://app.example.com/orders/1048/reject'),
]);

Button Styles and Colours

Google Chat supports four button styles. If no style is set, Google Chat renders an outlined button. Use the fluent helpers for the common styles or type() with ButtonType when the style is selected dynamically.

use NotificationChannels\GoogleChat\Enums\ButtonType;

$outlined = Button::text('View details')
    ->outlined()
    ->openUrl('https://app.example.com/orders/1048');

$primary = Button::text('Approve')
    ->filled()
    ->openUrl('https://app.example.com/orders/1048/approve');

$tonal = Button::text('Request changes')
    ->filledTonal()
    ->openUrl('https://app.example.com/orders/1048/request-changes');

$borderless = Button::text('Dismiss')
    ->borderless()
    ->openUrl('https://app.example.com/orders/1048/dismiss');

$dynamic = Button::text('Continue')
    ->type(ButtonType::FILLED)
    ->openUrl('https://app.example.com/orders/1048/continue');

Use color() to provide a custom background colour. Each RGB component, plus the optional alpha value, must be a normalised value from 0 to 1. Google Chat renders a button with a custom colour as filled, even if another type is set.

$danger = Button::text('Delete')
    ->icon('https://cdn.example.com/icons/delete.svg')
    ->iconAltText('Delete order')
    ->color(1, 0, 0, 0.9)
    ->openUrl('https://app.example.com/orders/1048/delete');

Use iconAltText() to describe the icon for assistive technology. This is distinct from altText(), which describes the button's action.

Button Overflow Menus

Use overflowMenu() when a button should reveal a list of secondary actions. Each OverflowMenuItem can have a start icon and either a URL or Google Chat action function.

use NotificationChannels\GoogleChat\Components\MaterialIcon;
use NotificationChannels\GoogleChat\Components\OverflowMenuItem;

$more = Button::text('More')
    ->icon(MaterialIcon::make('menu'))
    ->filled()
    ->overflowMenu([
        OverflowMenuItem::text('Open Chat')
            ->startIcon(MaterialIcon::make('chat'))
            ->openUrl('https://chat.google.com'),
        OverflowMenuItem::text('Refresh')->onClickAction('refresh'),
    ]);

ChipList & Chip

ChipList displays compact labels and actions. Chips can use the same known, URL, and Material icons as buttons, and can be disabled without removing them from the card.

use NotificationChannels\GoogleChat\Components\Chip;
use NotificationChannels\GoogleChat\Components\MaterialIcon;
use NotificationChannels\GoogleChat\Widgets\ChipList;

$section->chipList([
    Chip::label('Documentation')
        ->openUrl('https://developers.google.com/workspace/chat'),
    Chip::label('Alarm')
        ->icon(MaterialIcon::make('alarm'))
        ->iconAltText('Alarm')
        ->openUrl('https://example.com/alerts'),
    Chip::label('Unavailable')
        ->disabled()
        ->altText('This action is currently unavailable'),
]);

Chip lists wrap by default. To scroll chips horizontally instead, use horizontalScrollable() or layout(ChipListLayout::HORIZONTAL_SCROLLABLE).

use NotificationChannels\GoogleChat\Enums\ChipListLayout;

$chips = ChipList::make([
    Chip::label('One'),
    Chip::label('Two'),
])->layout(ChipListLayout::HORIZONTAL_SCROLLABLE);

Custom Interactivity Actions (onClickAction)

Buttons can trigger custom webhook actions or function callbacks instead of opening URLs:

Button::text('Run Diagnostics')
    ->onClickAction('triggerDiagnostics', [
        'serverId' => 'web-prod-01',
        'region' => 'eu-west-1',
    ]);

Divider

Divider inserts a clean horizontal dividing line between widgets:

use NotificationChannels\GoogleChat\Widgets\Divider;

$section->decoratedText('Item 1')
    ->widget(Divider::create())
    ->decoratedText('Item 2');

Or fluently on a section: $section->divider();.

Columns (Multi-Column Layouts)

Columns splits a section into side-by-side columns:

use NotificationChannels\GoogleChat\Widgets\Columns;
use NotificationChannels\GoogleChat\Widgets\DecoratedText;

$section->columns(function ($cols) {
    $cols->column([
        DecoratedText::create('GBP 1,200.00')->topLabel('Subtotal'),
    ]);
    $cols->column([
        DecoratedText::create('GBP 240.00')->topLabel('VAT (20%)'),
    ]);
    $cols->column([
        DecoratedText::create('GBP 1,440.00')->topLabel('Total Paid'),
    ]);
});

Aligning a Button List

Google Chat applies a widget's horizontal alignment only when it is inside a column. To right-align a button list, place it in a full-width column with HorizontalAlignment::END.

use NotificationChannels\GoogleChat\Components\Button;
use NotificationChannels\GoogleChat\Enums\HorizontalAlignment;
use NotificationChannels\GoogleChat\Enums\HorizontalSizeStyle;
use NotificationChannels\GoogleChat\Enums\VerticalAlignment;
use NotificationChannels\GoogleChat\Widgets\ButtonList;

$section->columns(function ($columns) {
    $columns->column(
        [
            ButtonList::create([
                Button::text('Cancel')->borderless(),
                Button::text('Save')->filled(),
            ]),
        ],
        horizontalSizeStyle: HorizontalSizeStyle::FILL_AVAILABLE_SPACE,
        horizontalAlignment: HorizontalAlignment::END,
        verticalAlignment: VerticalAlignment::CENTER,
    );
});

Set verticalAlignment to VerticalAlignment::TOP, ::CENTER, or ::BOTTOM to align the column's widgets vertically.

TextParagraph

TextParagraph renders a block of text supporting HTML tags (<b>, <i>, <u>, <strike>, <font>, <a href="...">, <br>) or converted Markdown:

use NotificationChannels\GoogleChat\Widgets\TextParagraph;

TextParagraph::create('Deployment logs for <b>web-prod-01</b> completed with <i>0 errors</i>.');

To convert GitHub or GitLab Markdown directly inside a text paragraph card widget, use markdown():

TextParagraph::make()->markdown($mergeRequest->description);

Use maxLines() to truncate long paragraphs after a specific number of displayed lines:

TextParagraph::create('Long deployment output...')->maxLines(2);

Image

Image renders a full-width image inside a section with optional click-through action:

use NotificationChannels\GoogleChat\Widgets\Image;

Image::create(
    imageUrl: 'https://cdn.example.com/charts/sales-q3.png',
    onClickUrl: 'https://analytics.example.com/reports/q3'
)->altText('Q3 Sales Performance Chart');

Grid

Grid presents related items in columns. Each GridItem can include an image, image crop and border style, title, subtitle, and text alignment. The grid itself can open a URL or trigger a Google Chat action.

use NotificationChannels\GoogleChat\Components\GridItem;
use NotificationChannels\GoogleChat\Enums\BorderType;
use NotificationChannels\GoogleChat\Enums\ImageCropStyle;
use NotificationChannels\GoogleChat\Enums\TextAlignment;
use NotificationChannels\GoogleChat\Widgets\Grid;

$section->grid(
    Grid::make([
        GridItem::make()
            ->image('https://cdn.example.com/products/keyboard.png')
            ->cropStyle(ImageCropStyle::SQUARE)
            ->borderStyle(BorderType::STROKE)
            ->title('Mechanical Keyboard')
            ->subtitle('In stock')
            ->textAlignment(TextAlignment::CENTER),
        GridItem::make()
            ->image('https://cdn.example.com/products/mouse.png')
            ->title('Wireless Mouse')
            ->textAlignment(TextAlignment::CENTER),
    ])
        ->title('Recommended products')
        ->columnCount(2)
        ->openUrl('https://app.example.com/products')
);

Available image crop styles are ImageCropStyle::SQUARE, ::CIRCLE, and ::RECTANGLE_4_3. Use BorderType::NO_BORDER or ::STROKE to control the image border.

Carousel

Carousel displays horizontally scrollable cards. A CarouselCard has a regular widget area and an optional footer widget area, both composed with the package's existing widgets.

use NotificationChannels\GoogleChat\Components\Button;
use NotificationChannels\GoogleChat\Components\CarouselCard;
use NotificationChannels\GoogleChat\Widgets\ButtonList;
use NotificationChannels\GoogleChat\Widgets\Carousel;
use NotificationChannels\GoogleChat\Widgets\Image;
use NotificationChannels\GoogleChat\Widgets\TextParagraph;

$section->carousel(
    Carousel::make([
        CarouselCard::make([
            Image::make('https://cdn.example.com/helpdesk.png')
                ->altText('Helpdesk'),
            TextParagraph::make('<b>Helpdesk</b>'),
            TextParagraph::make('Raise a ticket for support queries.'),
        ])->footerWidgets(
            ButtonList::make(
                Button::text('Raise a ticket')
                    ->openUrl('https://app.example.com/tickets')
            )
        ),
        CarouselCard::make([
            Image::make('https://cdn.example.com/guides.png')
                ->altText('Guides'),
            TextParagraph::make('<b>Workday guide</b>'),
        ]),
    ])
);

Use widgets() or addWidget() for a card's main content, and footerWidgets() or addFooterWidget() for its footer actions.

Overflow Menu Actions (CardAction)

CardAction adds menu items to the card's top-right overflow menu:

use NotificationChannels\GoogleChat\Card;
use NotificationChannels\GoogleChat\Components\CardAction;

$card->cardActions([
    CardAction::create('Export as PDF', 'https://example.com/invoices/1048.pdf'),
    CardAction::create('Print Invoice', 'https://example.com/invoices/1048/print'),
]);

Google API Reference

For further details on all available Google Chat widget properties and icon types, visit Google's API references:

• Google Chat API: Widget Objects Reference
• Google Chat API: Button Reference
• Google Chat API: DecoratedText Widget Reference
• Google Chat API: Known Icons Reference