Download the PHP package portavice/bladestrap without Composer

Bladestrap = Blade + Bootstrap

Bladestrap provides Laravel Blade components for the Bootstrap 5 frontend framework.

Contents

• Installation
  • Install Bootstrap
  • Configure Bladestrap
  • Customize views
• Usage
  • Alerts
  • Badges
  • Breadcrumb
  • Buttons
  • Button groups
  • Button toolbars
  • Dropdowns
  • Forms
  • Types of form fields
  • Options
  • Disabled, readonly, required
  • Input groups
  • Hints
  • Prefill values from query parameters
  • Error messages
  • Links
  • List groups
  • Modals
  • Navigation
• Usage without Laravel

Installation

First, install the package via Composer:

Within a Laravel application, the package will automatically register itself.

[!NOTE] If you only use parts of the Laravel framework (such as illuminate/view), make sure to follow the instructions in the section on usage without Laravel.

Install Bootstrap

Note that you need to include the Bootstrap files on your own.

1. If you haven't added Bootstrap as one of your dependencies, you can do so via npm:

2. Add the following to your webpack.mix.js to copy the required Bootstrap files to your public directory:

3. Include CSS and JavaScript in resources/views/layouts/app.blade.php:

You may need to adjust the steps above to your custom project configuration. If you have a custom Bootstrap build you are responsible to include the necessary parts of Bootstrap yourself.

Configure Bladestrap

Usually this should not be necessary, but if you need to overwrite the default configuration, create and edit config/bladestrap.php:

Customize views

If you want to customize the views, publish them to resources\views\vendor\bladestrap\components and edit them to meet your requirements:

You may want to delete the views you haven't changed to benefit from package updates automatically.

Usage

The components are placed in the bs namespace, such that they can be used via:

Components can be enhanced with additional classes from Bootstrap or your own CSS.

Specifically handled attributes are documented with type annotations in the @props in the respective Blade template under resources/views/components.

Alerts

Alerts are of variant alert-info by default and can be dismissible (with a close button).

Badges

Badges are of variant badge-primary default:

Breadcrumb

The breadcrumb container is a <x-bs::breadcrumb> (typically placed within your layouts/app.blade.php):

Items can be added via <x-bs::breadcrumb.item :href="route('route-name')">Title</x-bs::breadcrumb.item>.

Buttons

To create buttons or button-like links with Bootstrap's btn-* classes you can use

• <x-bs::button> (becomes a <button>)
• and <x-bs::button.link> (becomes an <a>). Per default btn-primary is used, you can change that with the variant.

To disable a button or link, just add disabled="true" which automatically adds the corresponding class and aria-disabled="true" as recommended by the Bootstrap documentation.

Button groups

Buttons can be grouped:

Button toolbars

Button groups can be grouped into a toolbar:

Dropdowns

Dropdown buttons can be added as follows:

The direction attribute can be used to set the direction of the dropdown overlay. It defaults to down. variant (default primary) is inherited from the button component.

Within the <x-slot:dropdown> you may place headers and items:

Note that Bootstrap's dropdowns require Popper, which needs to be included separately if you don't use Bootstrap's bootstrap.bundle.min.js.

Dropdown buttons within a button group require a nested button group and :nested-in-group="true" on the dropdown button:

Forms

Use <x-bs::form> to create forms (method defaults to POST), any additional attributes passed to the form component will be outputted as well:

Bladestrap will inject an CSRF token field for all methods except GET automatically. Bladestrap will also configure method spoofing for PUT, PATCH and DELETE forms.

Types of form fields

Bladestrap has wide support for Bootstrap's form fields.

Note that the content of the form field becomes the label. This allows to include icons etc. If you don't want to add a label, don't pass any content:

All attributes will be passed to the <input>, <select>, <textarea> - except

• the attributes which start with container- (those will be applied to the container for the label and input)
• and the attributes which start with label- (those will be applied to the label).

The following types are supported as values for the type attribute:

• checkbox - creates a normal checkbox, requires :options
• color
• date
• datetime-local*
• email
• file
• hidden - ignores slots for label, hint and input group
• month*
• number
• password
• radio - creates a radio, requires :options
• range
• select - creates a dropdown (<select> with <option>s), requires :options
• switch - creates a toggle switch, requires :options
• tel
• text
• textarea - creates a <textarea>
• time*
• url
• week*

The types (marked with *) listed above don't have full browser support.

Options

Radio buttons, checkboxes and selects need a :options attribute providing an iterable of value/label pairs, e.g.

• an array, as in :options="[1 => 'Label 1', 2 => 'Label 2']"
• an Illuminate\Support\Collection, such as
  • :options="User::query()->pluck('name', 'id')"
  • or :options="User::query()->pluck('name', 'id')->prepend(__('all'), '')"
• a Portavice\Bladestrap\Support\Options which allows to set custom attributes for each option. For checkboxes, radios and switches, custom attributes prefixed with check-container- or check-label- are applied to the .form-check or .form-check-label respectively. If labels contain HTML, set :allow-html="true".

An Portavice\Bladestrap\Support\Options can be used to easily create an iterable based on

• an array

• an enum implementing the BackedEnum interface

• an array or Illuminate\Database\Eloquent\Collection of Eloquent models (the primary key becomes the value, label must be defined)

Additional options can be prepended/appended to an Options:

Radio buttons (allows to select one of multiple values):

Multiple checkboxes (allows to select multiple values):

Single checkbox (just one option):

Select (allows to select one of multiple values):

Multi-Select (allows to select multiple values):

Disabled, readonly, required

The attributes :disabled, :readonly, and :required accept a boolean value, e.g. :disabled="true" or :required="isset($var)".

Per default fields with :required="true" are marked with a * after the label. This behavior can be disabled via configuration (for all fields) or with :mark-as-required="false" (for a single field).

Input groups

To add text at the left or the right of a form field (except checkboxes and radio buttons), you can use the slots <x-slot:prependText> and <x-slot:appendText> which makes an input group:

By default, the appended/prepended text is wrapped within a <label> class="input-group-text" associated with the field. To avoid this, set :container="false" attribute on the slot which allows to define to add buttons for example:

Alternatively, an appendText slot can include a <x-bs::form.field:nested-in-group="true">:

Hints

<x-slot:hint> can be used to add a text with custom hints (.form-text) below the field, which will be automatically referenced via aria-describedby by the input:

Prefill values from query parameters

Setting :from-query="true" will extract values from the query parameters of the current route.

A form with the example field above on a page /my-page?filter[name]=Test will set "Test" as the prefilled value of the field, while /my-page will have an empty value.

To pass default filters applied if no query parameters are set, use ValueHelper::setDefaults:

Error messages

All form fields show corresponding error messages automatically if present (server-side validation). If you want to show them independent of a form field, you can use the component directly:

Both <x-bs::form.feedback> and <x-bs::form.field> support to use another than the default error bag via the :errors attribute.

Links

Colored links can be placed via <x-bs::link>, the attributes opacity and opacityHover define opacity.

List groups

<x-bs::list> is a list group, a container for multiple <x-bs::list.item>. :flush="true" enables flush behavior, :horizontal="true changes the layout from vertical to horizontal.

Items can be added via <x-bs::list.item>:

:active="true" highlights the active item, :disabled="true" makes it appear disabled.

Modals

Modals can be created via <x-bs::modal> with optional slots for title and footer. Both slots accept additional classes and other attributes. If you don't want a <h1> container for the title, change it via container="h2" etc.

<x-bs::modal> supports the following optional attributes:

• centered to center the modal vertically (defaults to false)
• fade for the fade effect when opening the modal (defaults to true)
• fullScreen to force fullscreen (defaults to false, pass true to always enforce full screen or sm to enforce for sizes below the sm breakpoint etc.),
• scrollable to enable a vertical scrollbar for long dialog content (defaults to false)
• staticBackdrop' to enforce that clicking outside of it does not close the modal (defaults to false)
• closeButton sets the variant of the close button in the modal footer (defaults to secondary, false to disable the close button),
• closeButtonTitle for the title of the close button (defaults to "Close")

A <x-bs::modal.button modal="my-modal"> opens the modal with the ID my-modal. You may pass any additional attributes as known from <x-bs::button>.

Navigation

<x-bs::nav> creates a nav container, use container="ol" to change the container element from the default <ul> to <ol>.

Navigation items can be added via <x-bs::nav.item href="{{ route('route-name') }}">Current Page</x-bs::nav.item>.

A navigation item may open a dropdown if you enabled this by adding a dropdown slot:

Usage without Laravel

Bladestrap uses config() and request() helpers. If you want to use Bladestrap without Laravel, you need to define the two helpers in your application, for example (may need to be adapted to the framework you use):

In addition, you have to do the registrations of the BladestrapServiceProvider yourself: