GitLab Issues Component Demo

This page demonstrates the GitLab Issues component that can fetch and display issues from a GitLab repository.

Example queries

Loading GitLab issues...

Documentation

Basic Usage

<GitLabIssues
	gitlabUrl="https://gitlab.opencode.de"
	projectId="kern-ux/pattern-library"
	title="Project Issues"
/>

Example with Filters

The component below shows how to use various filters and field selections:

<GitLabIssues
	gitlabUrl="https://gitlab.opencode.de"
	projectId="kern-ux/pattern-library"
	state="opened"
	milestone="Backlog"
	fields={['title', 'state', 'assignees', 'labels', 'milestone', 'created_at']}
	maxResults={25}
	title="Produkt-Backlog"
/>

<GitLabIssues
	gitlabUrl="https://gitlab.opencode.de"
	projectId="kern-ux/pattern-library"
	state="opened"
	milestone="Roadmap"
	fields={['title', 'state', 'assignees', 'labels', 'milestone', 'created_at']}
	maxResults={25}
	title="Produkt-Roadmap"
/>

Example with Advanced Filters

The new filter prop allows you to use any GitLab API parameter for advanced filtering:

<GitLabIssues
	gitlabUrl="https://gitlab.opencode.de"
	projectId="kern-ux/pattern-library"
	filter="weight=5 AND issue_type=issue"
	title="High Weight Issues"
	fields={['title', 'weight', 'state', 'assignees', 'created_at']}
/>

Example with Date Range Filters

<GitLabIssues
	gitlabUrl="https://gitlab.opencode.de"
	projectId="kern-ux/pattern-library"
	filter="created_after=2025-01-01T00:00:00Z AND updated_before=2025-06-30T23:59:59Z"
	title="Issues from First Half of 2025"
	fields={['title', 'state', 'created_at', 'updated_at']}
	dateFormat="dd.MM.yyyy"
	dateLocale="de-DE"
/>

Example with Complex Filters

<GitLabIssues
	gitlabUrl="https://gitlab.opencode.de"
	projectId="kern-ux/pattern-library"
	filter="labels=bug,critical AND assignee_username=john.doe AND due_date=2025-12-31"
	title="Critical Bugs Due by Year End"
	fields={['title', 'due', 'assignees', 'labels', 'state']}
	fieldsHeaders={['Titel', 'Fällig am', 'Zugewiesen', 'Labels', 'Status']}
/>

Example with Custom Headers

<GitLabIssues
	gitlabUrl="https://gitlab.opencode.de"
	projectId="kern-ux/pattern-library"
	fields={['title', 'state', 'assignees', 'labels', 'created_at']}
	fieldsHeaders={['Titel', 'Status', 'Zugewiesen an', 'Etiketten', 'Erstellt am']}
	title="Localized Headers Example"
/>

Example with Custom Date Formatting

<GitLabIssues
	gitlabUrl="https://gitlab.opencode.de"
	projectId="kern-ux/pattern-library"
	fields={['title', 'due', 'created_at', 'updated_at']}
	fieldsHeaders={['Titel', 'Fällig am', 'Erstellt', 'Aktualisiert']}
	dateFormat="dd.MM.yyyy"
	dateLocale="de-DE"
	title="German Date Formatting Example"
/>

Example with Priority Column Hidden

<GitLabIssues
	gitlabUrl="https://gitlab.opencode.de"
	projectId="kern-ux/pattern-library"
	hidePriority={true}
	fields={['title', 'due', 'state', 'labels']}
	fieldsHeaders={['Titel', 'Fällig am', 'Status', 'Labels']}
	title="Issues without Priority Column"
/>

Example with Automatic Priority Sorting

<GitLabIssues
	gitlabUrl="https://gitlab.opencode.de"
	projectId="kern-ux/pattern-library"
	sortByPriority={true}
	fields={['title', 'due', 'state', 'labels']}
	fieldsHeaders={['Titel', 'Fällig am', 'Status', 'Labels']}
	title="Issues Sorted by Priority"
/>

Available Props

Prop	Type	Default	Description
`gitlabUrl`	string	-	GitLab instance URL, used only as a fallback when no GitLab proxy is configured
`apiToken`	string	-	Deprecated and ignored. Issues are read through the KERN chatbot's anonymous GitLab proxy, which authenticates server-side
`projectId`	string/number	-	Project ID or project path (e.g., 'group/project')
`milestone`	string	-	Filter by milestone title
`assignee`	string	-	Filter by assignee username
`state`	'opened'/'closed'/'all'	'opened'	Filter by issue state
`labels`	string	-	Filter by labels (comma-separated)
`filter`	string	-	Advanced GitLab API filters with AND operators. Supports multiple quote formats for values with spaces: single quotes ('Design'), double quotes ("In Review"), and mixed usage. Examples: 'weight=5 AND due_date=2025-12-31' or 'label=('Design', 'In Bearbeitung') AND issue_type=issue'
`fields`	string[]	['title', 'state', 'assignees', 'labels', 'created_at']	Fields to display as table columns
`fieldsHeaders`	string[]	-	Custom headers for the field columns (same order as fields)
`maxResults`	number	50	Maximum number of issues to fetch
`title`	string	'GitLab Issues'	Table title
`defaultSort`	string	-	Default sorting (e.g., 'title ASC', 'created_at DESC')
`dateFormat`	string	-	Date format string (e.g., 'dd-MM-yyyy', 'MMM-yy', 'dd.MM.yyyy')
`dateLocale`	string	'de-DE'	Locale for date formatting
`hideHeader`	boolean	false	Hide the table heading/title if set to true
`hidePriority`	boolean	false	Hide the automatically generated priority column based on Prio::1-xyz labels
`sortByPriority`	boolean	false	Automatically sort the table by priority column when priority labels are detected

Sorting Features

The table now supports interactive sorting:

Click any column header to sort by that field
First click: Sort ascending (A-Z, oldest first)
Second click: Sort descending (Z-A, newest first)
Third click: Remove sorting (back to original order)
Visual indicators: ▲ (ascending), ▼ (descending), ⇕ (sortable)

Default Sorting

Use the defaultSort prop to set initial sorting:

// Sort by title, ascending (default direction)
<GitLabIssues defaultSort="title" ... />

// Sort by creation date, descending
<GitLabIssues defaultSort="created_at DESC" ... />

// Sort by state, ascending (explicitly)
<GitLabIssues defaultSort="state ASC" ... />

Advanced Filtering

The new filter prop provides access to the full GitLab Issues API filtering capabilities. It supports any parameter from the GitLab Issues API with AND operators for combining multiple conditions.

Filter Examples

// Filter by weight and issue type
<GitLabIssues
  filter="weight=5 AND issue_type=issue"
  ...
/>

// Filter by date range
<GitLabIssues
  filter="created_after=2025-01-01T00:00:00Z AND updated_before=2025-06-30T23:59:59Z"
  ...
/>

// Filter by assignee and labels
<GitLabIssues
  filter="assignee_username=john.doe AND labels=bug,critical"
  ...
/>

Available Filter Parameters

Common filter parameters include:

weight - Issue weight (1-10)
due_date - Due date (YYYY-MM-DD or 'None')
assignee_username - Assignee username
assignee_id - Assignee user ID
author_username - Issue author username
created_after / created_before - Date range filters
updated_after / updated_before - Update date filters
issue_type - Type (issue, incident, test_case)
epic_id - Epic ID
my_reaction_emoji - User's reaction

Use ISO 8601 format for dates: YYYY-MM-DDTHH:MM:SSZ

Date Formatting

The component supports custom date formatting for all date fields (created_at, updated_at, closed_at, due):

Format Strings

You can use standard date format patterns:

dd-MM-yyyy → 27-05-2025 (German style)
MM/dd/yyyy → 05/27/2025 (US style)
dd.MM.yyyy → 27.05.2025 (Common European style)
yyyy-MM-dd → 2025-05-27 (ISO style)
MMM dd, yyyy → Mai 27, 2025 (Month abbreviation)
dd MMM yy → 27 Mai 25 (Short format)

Locale Support

The dateLocale prop controls the language used for month names, locale-specific formatting, and interface text translations:

// German locale with German date format
<GitLabIssues
  dateFormat="dd. MMMM yyyy"
  dateLocale="de-DE"
  ...
/>
// Output: "27. Mai 2025"
// Interface text: "(keine)" for issues without labels

// English locale with US date format
<GitLabIssues
  dateFormat="MMMM dd, yyyy"
  dateLocale="en-US"
  ...
/>
// Output: "May 27, 2025"
// Interface text: "No labels" for issues without labels

Note: Sorting is always performed on the original date values before formatting is applied, ensuring correct chronological order regardless of the display format.

Available Fields

The following fields can be used in the fields prop:

id - GitLab issue ID
iid - Project-specific issue number
title - Issue title (clickable link to GitLab)
state - Issue state (opened/closed)
assignees - Assigned users with avatars
author - Issue author
labels - Issue labels as badges
milestone - Associated milestone
created_at - Creation date
updated_at - Last update date
closed_at - Closure date (if closed)
weight - Issue weight
web_url - Link to GitLab issue

Authentication

The component does not authenticate against GitLab from the browser. All reads go through the anonymous, read-only GitLab proxy published by the KERN chatbot backend ($DOCUSAURUS_CHATBOT_URL/api/gitlab), which adds the credentials server-side. No GitLab API token is part of the site bundle any more.

The proxy only serves the projects on its allowlist and only the issues, labels and milestones resources — everything else answers 404 Not Found.

Configuring the proxy

Override the proxy origin (for example to develop against a local backend) via the environment:

# defaults to $DOCUSAURUS_CHATBOT_URL/api/gitlab
DOCUSAURUS_GITLAB_PROXY_URL="http://localhost:8000/api/gitlab"

// No token anywhere — the proxy handles authentication
<GitLabIssues
	gitlabUrl="https://gitlab.opencode.de"
	projectId="kern-ux/pattern-library"
	milestone="Backlog"
	title="Issues from the GitLab proxy"
/>

This approach is especially useful for:

Production deployments, where tokens must never reach the client
CI/CD environments, which no longer need a GitLab token to build the site
Development setups, which work without any personal token

Error Handling

The component includes comprehensive error handling:

API connection errors
Authentication failures
Invalid project IDs
Network timeouts
Rate limiting

Errors are displayed in a user-friendly format with helpful messages.

Live Example

note

To see a live example, you would need to provide valid GitLab credentials:

<GitLabIssues
	gitlabUrl="https://gitlab.com"
	projectId="your-group/your-project"
	state="opened"
	fields={['title', 'state', 'assignees', 'created_at']}
	maxResults={10}
	title="Live GitLab Issues"
/>

Styling

The component uses CSS modules for styling and respects Docusaurus theme variables:

Uses --ifm-color-primary for headers and accents
Responsive design with mobile-friendly tables
Dark mode support through CSS variables
Hover effects and smooth transitions

You can customize the styling by overriding the CSS classes in your custom CSS.

Interactive Tooltips

The component includes interactive tooltips powered by react-tooltip that provide additional information when hovering over certain elements:

Issue Titles: Hover over any issue title to see detailed information including:
- Full issue title
- Issue ID (#123)
- Current state (opened/closed)
- Creation date
- Truncated description (if available)
Assignees: Hover over the assignees field to see:
- Complete list of all assignees
- Full names and usernames
- "No assignees" message for unassigned issues
Labels: Hover over the labels area to see:
- Enhanced visual display of all labels
- Color-coded label badges
- Label descriptions (if available)
- Priority labels are filtered out to avoid duplication with the priority column
Individual Labels: Hover over any individual label to see:
- The specific description text for that label
- Uses react-tooltip for consistent styling and behavior

Dark theme with high contrast for readability
Consistent styling with the GitLab Gantt component
Responsive design that works on different screen sizes
Smooth animations and proper z-index layering

Priority Column

The GitLabIssues component automatically detects priority labels that follow the pattern Prio::[1-5]-xyz (e.g., Prio::1-High, Prio::2-Medium, Prio::3-Low) and generates a special priority column when such labels are found in the issues.

Automatic Detection: The component scans all issue labels for the priority pattern
Column Insertion: The priority column is automatically inserted as the third column (after 'title' and 'due')
Priority Display: Shows the priority number (1-5) extracted from the label
Label Filtering: Priority labels are filtered out from the regular labels column to avoid duplication
Hide Option: Use hidePriority={true} to suppress the automatic priority column generation
Auto-Sorting: Use sortByPriority={true} to automatically sort the table by priority when priority labels are detected

Priority Label Examples:

Prio::1-Critical → Priority: 1
Prio::2-High → Priority: 2
Prio::3-Medium → Priority: 3
Prio::4-Low → Priority: 4
Prio::5-Minor → Priority: 5

Automatic Priority Sorting

When sortByPriority={true} is set and priority labels are detected in the issues:

The table will automatically sort by the priority column in ascending order (1, 2, 3, 4, 5)
This only applies when no defaultSort is specified
Priority sorting respects the existing interactive sorting functionality - users can still click column headers to change sorting
The priority column must not be hidden (hidePriority should be false or omitted)

<GitLabIssues
	gitlabUrl="https://gitlab.opencode.de"
	projectId="kern-ux/pattern-library"
	sortByPriority={true}
	title="Auto-sorted by Priority"
	fields={['title', 'due', 'state', 'labels']}
	fieldsHeaders={['Titel', 'Fällig am', 'Status', 'Labels']}
/>

Pagination Features

The component now supports client-side pagination to handle large result sets efficiently:

Basic Pagination Example

<GitLabIssues
	gitlabUrl="https://gitlab.opencode.de"
	projectId="kern-ux/pattern-library"
	pageSize={5}
	title="Paginated Issues (5 per page)"
	fields={['title', 'state', 'labels', 'created_at']}
	dateFormat="dd.MM.yyyy"
	dateLocale="de-DE"
/>

Pagination with Larger Page Size

<GitLabIssues
	gitlabUrl="https://gitlab.opencode.de"
	projectId="kern-ux/pattern-library"
	pageSize={10}
	title="More Issues per Page (10 per page)"
	fields={['title', 'due', 'state', 'assignees']}
	defaultSort="due ASC"
/>

Pagination Features:

Page Size Control: Use the pageSize prop to limit the number of rows displayed per page
Navigation Controls: Four navigation buttons are provided:
- << - Go to first page
- < - Go to previous page
- > - Go to next page
- >> - Go to last page
Page Information: Shows current page and total pages (e.g., "Page 2 of 5")
Item Count: Displays range of currently visible items (e.g., "Showing 6-10 of 23 issues")
Auto-reset: When sorting changes or new data is loaded, pagination automatically resets to page 1
Responsive Design: Pagination controls adapt to smaller screens

Live Pagination Examples

Loading GitLab issues...

Pagination Prop

Prop	Type	Default	Description
`pageSize`	number	-	Maximum number of rows to display per page. If not provided, all results are shown without pagination
`hideHeader`	boolean	false	Hide the table heading/title if set to true

Header Control Examples

Hidden Header Example

Loading GitLab issues...

Note: The above table has no header/title because hideHeader={true} is set.

Comparison: With Header vs Without Header

With Header (default):

Loading GitLab issues...

Without Header:

Loading GitLab issues...

Enhanced Filter Examples with Single Quotes and Spaces

The component now supports single quotes and values with spaces:

// German labels with spaces using single quotes
<GitLabIssues
	gitlabUrl="https://gitlab.opencode.de"
	projectId="kern-ux/pattern-library"
	filter="label=('Design', 'In Bearbeitung') AND issue_type=issue AND milestone_id=Started"
	fields={['title', 'labels', 'state']}
	fieldsHeaders={['Titel', 'Labels', 'Status']}
	title="German Labels with Spaces Example"
	hidePriority={true}
/>

// Mixed quotes and complex filtering
<GitLabIssues
  gitlabUrl="https://gitlab.opencode.de"
  projectId="kern-ux/pattern-library"
  filter="assignee_username in ('john.doe', 'jane.smith') AND label=('Design System', \"Quality Assurance\")"
  fields={['title', 'assignees', 'labels']}
  fieldsHeaders={['Titel', 'Zugewiesen', 'Labels']}
  title="Mixed Quotes Example"
  hidePriority={true}
/>

GitLab Issues Component Demo

Example queries

Documentation

Basic Usage

Example with Filters

Example with Advanced Filters

Example with Date Range Filters

Example with Complex Filters

Example with Custom Headers

Example with Custom Date Formatting

Example with Priority Column Hidden

Example with Automatic Priority Sorting

Available Props

Sorting Features

Default Sorting

Advanced Filtering

Filter Examples

Available Filter Parameters

Date Formatting

Format Strings

Locale Support

Available Fields

Authentication

Configuring the proxy

Error Handling

Live Example

Styling

Interactive Tooltips

Tooltip Features

Tooltip Styling

Priority Column

Priority Label Examples:

Automatic Priority Sorting

Header Control Examples

Hidden Header Example

Comparison: With Header vs Without Header

Enhanced Filter Examples with Single Quotes and Spaces

Inhaltsverzeichnis

Example queries

Documentation

Basic Usage​

Example with Filters​

Example with Advanced Filters​

Example with Date Range Filters​

Example with Complex Filters​

Example with Custom Headers​

Example with Custom Date Formatting​

Example with Priority Column Hidden​

Example with Automatic Priority Sorting​

Available Props​

Sorting Features​

Default Sorting​

Advanced Filtering​

Filter Examples​

Available Filter Parameters​

Date Formatting​

Format Strings​

Locale Support​

Available Fields​

Authentication​

Configuring the proxy​

Error Handling​

Live Example​

Styling​

Interactive Tooltips​

Tooltip Features​

Tooltip Styling​

Priority Column​

Priority Label Examples:​

Automatic Priority Sorting​

Pagination Features​

Basic Pagination Example​

Pagination with Larger Page Size​

Pagination Features:​

Live Pagination Examples​

Pagination Prop​

Header Control Examples​

Hidden Header Example​

Comparison: With Header vs Without Header​

Enhanced Filter Examples with Single Quotes and Spaces​

Inhaltsverzeichnis

Basic Usage

Example with Filters

Example with Advanced Filters

Example with Date Range Filters

Example with Complex Filters

Example with Custom Headers

Example with Custom Date Formatting

Example with Priority Column Hidden

Example with Automatic Priority Sorting

Available Props

Sorting Features

Default Sorting

Advanced Filtering

Filter Examples

Available Filter Parameters

Date Formatting

Format Strings

Locale Support

Available Fields

Authentication

Configuring the proxy

Error Handling

Live Example

Styling

Interactive Tooltips

Tooltip Features

Tooltip Styling

Priority Column

Priority Label Examples:

Automatic Priority Sorting

Pagination Features

Basic Pagination Example

Pagination with Larger Page Size

Pagination Features:

Live Pagination Examples

Pagination Prop

Header Control Examples

Hidden Header Example

Comparison: With Header vs Without Header

Enhanced Filter Examples with Single Quotes and Spaces