Material Components for Laravel

This package provides Blade components to use Material Components with Laravel.

Installation

Add the package with Composer:

composer require contextmapp/laravel-material-components

If you use Laravel 5.4 or later, the package's service provider registers itself with your application. Otherwise, you should add the provider to your application config in config/app.php:

<?php

return [
    // ...
    
    'providers' => [
        // ...
    
        Contextmapp\MaterialComponents\MaterialComponentsServiceProvider::class,
    ],
];

Components

The components are available under the mdc namespace.

Include the MDC stylesheet and script bundles.

<link rel="stylesheet" href="https://unpkg.com/material-components-web@latest/dist/material-components-web.min.css">
<script src="https://unpkg.com/material-components-web@latest/dist/material-components-web.min.js"></script>

To make use of the Material Icons, include the icon font:

<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">

All components have the data-mdc-auto-init attribute set, so they will be initialized automatically when mdc.autoInit() is called.

Buttons

Component: mdc::button

Example:

@component('mdc::button', ['type' => 'submit', 'icon' => 'add'])
    Button label
@endcomponent

Slots:

Default: the button label

Parameters:

type: The type of button (values: button, submit, link, default: button)
url: The URL to link the button to (required when type is link)
icon: The name of the icon to add to the button
iconClass: The class to apply to button icon (default: material-icons)
method: The _method field value for when the button is activated
form: The form ID you want to target with the button (if the button is outside the form)
variant: The Material Design spec button variant (allowed: unelevated, raised, outlined, dense, default: none)

Floating Action Button

Component: mdc::fab

Example:

@component('mdc::fab', ['icon' => 'person_add'])
    Add user
@endcomponent

Slots:

Default: the button label

Parameters:

url: The URL to link the FAB to
icon: required - The name of the icon for the FAB
iconClass: The class to apply to the button icon (default: material-icons)
extended: Toggle the extended FAB variant (default: false)
mini: Toggle the mini FAB variant (default: false)

Cards

Component: TODO

Chips

Component: TODO

Dialogs

Component: mdc::dialog

The dialog component contains a form, so you can easily add form components to add interactivity to it. Add a submit button as one of the form actions and you're done. When included in a Laravel framework application, the CSRF-field is added automatically.

Example:

@component('mdc::dialog', ['id' => 'some-dialog'])
    @slot('title', 'Do you want to continue?')
    
    Caution: there might be dragons ahead. Or maybe a grue.
    
    @slot('footer')
        @component('mdc::dialog.action', ['action' => 'cancel'])
            Cancel
        @endcomponent
        @component('mdc::dialog.action', ['action' => 'accept'])
            Continue
        @endcomponent
    @endslot
@endcomponent

Slots:

Default: the dialog body
title: The dialog title component
footer: The dialog footer, containing the action buttons

Parameters:

id: required - The dialog ID to refer to when interacting with the dialog
action: The endpoint for the form to submit to
method: The HTTP method to use when submitting the form (you can override this with a specific action button)
scroll: Flag to indicate the dialog body is scrollable (default: false)

Dialog actions

Component: mdc::dialog.action

Example:

@component('mdc::dialog.action', ['action' => 'cancel'])
    Cancel
@endcomponent

Slots:

Default: the button label

Parameters:

action: required - The dialog action (allowed: accept, cancel)
type: The button type (allowed: button, submit, default: button)

Drawers

Component: mdc::drawer

Example:

@component('mdc::drawer', ['id' => 'main-nav', 'type' => 'persistent'])
    @component('mdc::list.item', ['url' => url('/users'), 'activated' => true])
        @slot('icon', 'person')
        Users
    @endcomponent
    @component('mdc::list.item', ['url' => url('/settings')])
        @slot('icon', 'settings')
        Settings
    @endcomponent
@endcomponent

Slots:

Default: the drawer contents
header: the drawer header (if omitted, adds a toolbar spacer to the drawer)

Parameters:

id: required - The drawer ID to refer to when interacting with the drawer
type: required - The drawer variant (allowed: persistent, temporary)
open: Flag to render the drawer as opened by default

Image List

Component: TODO

Inputs and controls

For all inputs, the default slot functions as the label of the component.

Shared parameters:

field: required - The name to give to the input. This will automatically determine the old value if the form was previously submitted
value: The value for the field
required: Flag to toggle required state of input
disabled: Flag to toggle disabled state of input
autofocus Flag to toggle autofocus state of input

Checkboxes

Component: mdc::checkbox

Example:

@component('mdc::checkbox', ['field' => 'terms_of_service'])
    I agree to the <a href="{{ url('/terms') }}">Terms of Service</a>;
@endcomponent

Parameters:

valueOn: The value to submit when the checkbox is checked (default: 1)
valueOff: The value to submit when the checkbox is unchecked (default: 0)
checked: Set the checked state of the checkbox. (default: determined automatically from the value field)

Form field

Component: mdc::form-field

You'll mostly won't use this component directly, as it is included with the other input controls by default.

Example:

@component('mdc::form-field', ['id' => 'my-checkbox'])
    {{-- Some control --}}
    @slot('label')
        A label for the control
    @endslot
@endcomponent

Slots:

Default: the input control
label: the input label

Parameters:

id: required - The ID of the input control
align_end: Flag to move the input control to the end of the form field

Radios

Component: mdc::radio

Example:

@component('mdc::radio', ['field' => 'season', 'value' => 'winter', 'checked' => true])
    Winter
@endcomponent
@component('mdc::radio', ['field' => 'season', 'value' => 'summer'])
    Summer
@endcomponent

Parameters:

value: required - The value to set when selected
checked: Mark the option as selected

Select

Component: mdc::select

Example:

@component('mdc::select', ['field' => 'pizza'])
    Your favorite pizza
    @slot('options')
        <option value="hawaii">Hawaii</option>
        <option value="pepperoni">Pepperoni</option>
        <option value="margherita">Margherita</option
    @endslot
@endcomponent

Slots:

options: The slot containing the selectable options

Parameters:

This component has no additional parameters

Sliders

Component: TODO

Switches

Component: mdc::switch

Example:

@component('mdc::switch', ['field' => 'auto_update'])
    Update automatically
@endcomponent

Parameters:

valueOn: The value to submit when the checkbox is checked (default: 1)
valueOff: The value to submit when the checkbox is unchecked (default: 0)
checked: Set the checked state of the checkbox. (default: determined automatically from the value field)

Text Field

Component: mdc::text-field

Example:

@component('mdc::text-field', ['field' => 'email', 'type' => 'email'. 'required' => true])
    @slot('value', $user->email)
    E-mail Address
@endcomponent

Parameters:

type: The type of input (default: text)
variant: The text field variant (allowed: fullwidth, textarea, outlined, default: none)
icon: The icon to add to the text field
iconClass: The icon class to apply to the icon (default: material-icons)
iconPlacement: Where to place the icon (allowed: leading, trailing, default: leading)
help: The help text for the text field

Text Field Helper Text

Component: mdc::text-field.helper-text

You'll mostly won't use this component directly, as it is included with the other input controls by default.

Example:

@component('mdc::text-field.helper-text', ['id' => 'file-picker-description'])
    Choose a square image, at least 250px wide
@endcomponent

Slots:

Default: the help text to display

Parameters:

id: required - The ID to use for aria-describedby and aria-controls on the text field
persistent: Flag to make help text permanently visible
validation: Flag to indicate help text is validation message

Lists

Components: mdc::list

Example:

@component('mdc::list', ['two_line' => true])
    {{-- Insert some 'mdc::list.item' components here --}}
@endcomponent

Parameters:

non_interactive: Flag to toggle non-interactive list variant
dense: Flag to toggle dense list variant
avatars: Flag to toggle avatar list variant
two_line: Flag to toggle two-line list variant

List items

Components: mdc::list.item

Example of a regular list item with icon:

@component('mdc::list.item', ['icon' => 'group', 'url' => url('/groups')])
    Groups
@endcomponent

Example of a two line list item with avatar:

@component('mdc::list.item', ['avatar' => url('/users/john-doe.png')])
    @slot('primary', 'John Doe')
    @slot('secondary', '[email protected]')
@endcomponent

Slots:

Default: The text contents of the item (when primary slot is set, this will override default slot contents)
primary: The primary text content of the item
secondary: The secondary text content of the item
graphic: The first tile for the list item (can also be set through icon or avatar properties)
meta: The last tile for the list item

Parameters:

url: The URL to point the list item to
avatar: The URL to the avatar to use as the list item graphic
icon: The icon to use as the list item graphic
iconClass: The icon class for the list item graphic (default: material-icons)
selected: Flag to toggle the list item as selected
activated: Flag to toggle the list item as activated

Menus

Components: mdc::menu

Example:

@component('mdc::menu', ['id' => 'some-menu'])
    {{-- Populate the menu with 'mdc::list.item' components --}}
@endcomponent

Parameters:

id: required - The menu ID to refer to when interacting with the menu

Snackbars

Component: mdc::snackbar

Example:

@component('mdc::snackbar')
@endcomponent

Parameters:

This component has no parameters

Tabs

Component: TODO

Toolbars

Component: mdc::toolbar

Example:

@component('mdc::toolbar')
    Users
    @slot('actions')
        @component('mdc::toolbar.action', ['url' => url('/archive'), 'icon' => 'archive'])
            Archived users
        @endcomponent
    @endslot
@endcomponent

Slots:

Default: The toolbar title
up: The slot for the upward navigation action on the toolbar, used for the mdc::toolbar.menu-action component in most cases
actions: The contents of the end-aligned toolbar section, used with mdc::toolbar.action components in most cases

Parameters:

This component has no parameters

Component: mdc::toolbar.menu-action

Example:

@component('mdc::toolbar.menu-action', ['url' => url('/'), 'icon' => 'arrow_back'])
    Return to index
@endcomponent

Slots:

Default: the label for the toolbar action

Parameters:

icon: required - The icon to use on the toolbar action
iconClass: The icon class for the toolbar action (default: material-icons)
url: The URL for the toolbar action

Component: mdc::toolbar.action

Example:

@component('mdc::toolbar.action', ['url' => url('/search'), 'icon' => 'search'])
    Search
@endcomponent

Slots:

Default: the label for the toolbar action

Parameters:

icon: required - The icon to use on the toolbar action
iconClass: The icon class for the toolbar action (default: material-icons)
url: The URL for the toolbar action

Top App Bar

Component: mdc::top-app-bar

This component mimics the toolbar component in most aspects, refer to the toolbar section for more information

Example:

@component('mdc::top-app-bar')
    {{ config('app.name') }}
    @slot('actions')
        @component('mdc::top-app-bar.action', ['url' => url('/archive'), 'icon' => 'archive'])
            Archived users
        @endcomponent
    @endslot
@endcomponent

Slots:

Default: The contents of the start-aligned app bar section
actions: The contents of the end-aligned app bar section

Parameters:

This component has no parameters

Material Components for Laravel

Installation

Components

Buttons

Floating Action Button

Cards

Chips

Dialogs

Dialog actions

Drawers

Image List

Inputs and controls

Checkboxes

Form field

Radios

Select

Sliders

Switches

Text Field

Text Field Helper Text

Lists

List items

Menus

Snackbars

Tabs

Toolbars

Toolbar menu action

Toolbar action

Top App Bar