README.md

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', 'john.doe@example.com')
@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

Toolbar menu action

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

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