Component Library

User-Facing Components

The starter provides a series of custom Blade components that leverage Bootstrap 5 styling. These components are specifically designed for the user-facing interface of your application. For more information about the dual UI architecture, see the UI Architecture documentation.

The starter includes reusable, accessible, and customizable Blade components that integrate seamlessly with the Northwestern Laravel UI stack.

---

Navigation Components

Breadcrumbs

A Bootstrap-based breadcrumb navigation component that automatically handles the last item as active and supports both named routes and direct URLs.

Parameters

Parameter	Type	Required	Description
breadcrumbs	array<string, string>	Yes	An associative array where keys are route names (or URLs) and values are the display labels

Features

• Automatic Active State: The last breadcrumb is automatically marked as active
• Named Routes & URLs: Accepts both Laravel named routes and direct URLs
• Cypress Testing Support: Includes data-cy attributes for automated testing

Usage Example

<x-breadcrumbs :breadcrumbs="[
    'home' => 'Home',
    'dashboard.index' => 'Dashboard',
    'users.index' => 'Users',
    'users.show' => 'John Doe'
]" />

With Direct URLs:

<x-breadcrumbs :breadcrumbs="[
    'home' => 'Home',
    'https://example.com/external' => 'External Link',
    'users.index' => 'Users'
]" />

---

Interactive Components

Clipboard

A feature-rich copy-to-clipboard component with visual feedback, tooltips, and flexible styling options. Uses ClipboardJS for reliable cross-browser copying functionality.

Parameters

Parameter	Type	Required	Default	Description
text	string	Yes	-	The text content to copy to the clipboard
label	string|null	No	null	Optional label text to display alongside the icon
isButton	bool	No	true	Render as a button (true) or inline span (false)
buttonSize	string|null	No	null	Bootstrap button size: sm or lg
buttonVariant	string	No	outline-secondary	Bootstrap button variant for the default state
successVariant	string	No	outline-success	Bootstrap button variant for the success state
iconPosition	string	No	left	Icon position: left, right, or none

Valid Button Variants

The component accepts any standard Bootstrap 5 button variant:

• Solid: primary, secondary, success, danger, warning, info, light, dark, link
• Outline: outline-primary, outline-secondary, outline-success, outline-danger, outline-warning, outline-info, outline-light, outline-dark

Usage Examples

Basic Button:

<x-clipboard text="Hello World" />

With Label:

<x-clipboard
    text="user@example.com"
    label="Email Address"
    button-variant="primary"
/>

Small Button:

<x-clipboard
    text="{{ $accessToken }}"
    label="Copy Token"
    button-size="sm"
/>

Inline Span (No Button):

<x-clipboard
    :text="$user->id"
    label="Copy ID"
    :is-button="false"
/>

Icon on Right:

<x-clipboard
    text="https://example.com/share/12345"
    label="Share Link"
    icon-position="right"
    button-variant="success"
/>

No Icon (Label Only):

<x-clipboard
    text="{{ $secret }}"
    label="Copy Secret"
    icon-position="none"
/>

Custom Styling with Classes:

<x-clipboard
    text="{{ $code }}"
    label="Copy Code"
    class="w-100"
/>

---

Form Components

Select

A powerful, searchable select component built on Tom Select with support for multiple selection, asynchronous search, plugins, and advanced features. Designed to work seamlessly with Livewire.

Parameters

Parameter	Type	Required	Default	Description
id	string	Yes	-	Unique identifier for the select element
options	array|Collection	Yes	-	Options for the select (arrays, Collections, or Enums)
settings	array	No	[]	Additional Tom Select settings (merged with defaults)
plugins	array	No	[]	Tom Select plugins to enable with optional configurations
searchable	bool	No	true	Enable/disable search functionality
searchUrl	string	No	”	URL for asynchronous search API endpoint
optionCountSingularNoun	string	No	Item	Singular noun for the option count plugin
optionCountPluralNoun	string|null	No	Auto-generated	Plural noun for the option count plugin
maxOptions	int|null	No	30	Maximum number of options to display

Available Plugins

The Select component supports the following Tom Select plugins:

• caret_position - Adjust caret position in input
• change_listener - Listen for changes
• checkbox_options - Add checkboxes to options
• clear_button - Add a clear all button
• drag_drop - Drag and drop to reorder
• dropdown_header - Custom dropdown header
• dropdown_input - Input field in dropdown
• input_autogrow - Auto-grow input width
• no_active_items - Disable active item behavior
• no_backspace_delete - Disable backspace deletion
• optgroup_columns - Display optgroups as columns
• remove_button - Add remove buttons to items
• restore_on_backspace - Restore item on backspace
• virtual_scroll - Virtual scrolling for large lists
• option_count - Display option count (custom plugin)

See the Tom Select Plugins Documentation for detailed plugin options.

Features

• Multiple Data Formats: Supports arrays, Collections, Enums (both Unit and Backed)
• Optgroup Support: Nested arrays automatically render as optgroups
• Async Search: Built-in support for server-side search with automatic throttling (250ms)
• Enum Integration: Automatic label resolution for enums with label() method
• Accessibility: Proper ARIA attributes and semantic HTML

Usage Examples

Basic Select:

<x-select
    id="country"
    :options="['us' => 'United States', 'ca' => 'Canada', 'mx' => 'Mexico']"
/>

With Collection:

<x-select
    id="users"
    :options="$users->pluck('name', 'id')"
    placeholder="Select a user"
/>

With Enums:

<x-select
    id="affiliation"
    :options="App\Enums\AffiliationEnum::cases()"
/>

With Optgroups:

<x-select
    id="locations"
    :options="[
        'North America' => [
            'us' => 'United States',
            'ca' => 'Canada'
        ],
        'Europe' => [
            'uk' => 'United Kingdom',
            'de' => 'Germany'
        ]
    ]"
/>

Multiple Selection with Plugins:

<x-select
    id="tags"
    :options="$tags"
    :plugins="['checkbox_options', 'remove_button', 'clear_button']"
    multiple
/>

Async Search:

<x-select
    id="users-search"
    :options="[]"
    search-url="{{ route('api.users.search') }}"
    placeholder="Type to search users..."
/>

With Custom Settings:

<x-select
    id="priority"
    :options="['low' => 'Low', 'medium' => 'Medium', 'high' => 'High']"
    :settings="[
        'selectOnTab' => true,
        'closeAfterSelect' => true,
        'maxItems' => 3
    ]"
/>

With Option Count Plugin:

<x-select
    id="courses"
    :options="$courses"
    :plugins="['option_count' => true]"
    option-count-singular-noun="Course"
    option-count-plural-noun="Courses"
/>

Non-Searchable Select:

<x-select
    id="status"
    :options="['active' => 'Active', 'inactive' => 'Inactive']"
    :searchable="false"
/>

Livewire Integration:

<x-select
    id="department"
    :options="$departments"
    wire:model="selectedDepartment"
    ignore-livewire-updates
/>

Async Search API Response Format

When using search-url, your API endpoint should return JSON in this format:

[
    {"value": "1", "text": "Option 1"},
    {"value": "2", "text": "Option 2"}
]

The component automatically sends these query parameters:

• q: The search query string
• l: The maximum number of options to return

---

Northwestern Specific Components

Wildcard Photo

Displays a user’s Wildcard ID photo from Northwestern’s identity system. The component handles photo caching, URL generation with cache busting, and provides lazy loading for performance.

Parameters

Parameter	Type	Required	Description
user	User|null	Yes	The User model instance to display the photo for

Features

• Cache Busting: Automatically includes a cache-busting parameter based on wildcard_photo_last_synced_at
• Lazy Loading: Images load lazily to improve page performance
• Fallback Support: Gracefully handles missing photos with a default route

Usage Examples

Basic Usage:

<x-wildcard-photo :user="$user" />

With Custom Classes:

<x-wildcard-photo
    :user="$user"
    class="border-3"
/>

With Custom Size:

<x-wildcard-photo
    :user="$user"
    class="img-thumbnail"
    style="width: 150px; height: 150px;"
/>