Documentation

Everything you need to integrate IssueCapture

Installation

Add IssueCapture to your website in 3 simple steps:

1Add the Script

Include the IssueCapture widget script in your HTML, right before the closing </body> tag:

<script type="module">
  import IssueCapture from 'https://issuecapture.com/widget.js';
</script>

Performance: Only 32KB gzipped initial load. Screenshot & annotation tools (152KB) load on-demand.

2Initialize the Widget

Initialize IssueCapture with your API key:

<script type="module">
  import IssueCapture from 'https://issuecapture.com/widget.js';
  IssueCapture.init({
    apiKey: 'your_api_key_here'
  });
</script>

Note:

You can find your API key in your dashboard.

3Add a Trigger

Add a button or element to trigger the widget:

<button id="feedback">Report Issue</button>

<script type="module">
  import IssueCapture from 'https://issuecapture.com/widget.js';
  IssueCapture.init({
    apiKey: 'your_api_key_here',
    trigger: '#feedback'  // CSS selector for trigger element
  });
</script>

Done!

Your widget is now ready to collect issues.

Configuration

Most settings are configured in your dashboard

Theme, title, components, and features are set once in the dashboard UI. Only runtime options need to be passed in code.

Required

{
  apiKey: 'string'       // Your IssueCapture API key
}

Optional Runtime Options

{
  // Trigger
  trigger: 'string',                   // CSS selector for trigger button

  // Current User (dynamic per user)
  user: {
    name: 'string',                    // Pre-fill user name
    email: 'string'                    // Pre-fill user email
  },

  // Programmatic Field Defaults (NEW!)
  defaultValues: {
    priority: 'string',                // Set default priority (High, Medium, Low)
    component: 'string',               // Set default component/team
    labels: ['string'],                // Pre-select labels
    customFields: {                    // Set custom field values
      'customfield_10001': 'value'
    }
  },

  // Callbacks (custom behavior)
  onSubmit: function(data) {},         // Called after successful submission
  onOpen: function() {},               // Called when widget opens
  onClose: function() {},              // Called when widget closes
  onError: function(error) {}          // Called on error
}

Dashboard Settings

These are configured once in your dashboard and automatically loaded:

Widget title and description
Theme colors (primary, background)
Component/team options (synced from Jira)
Screenshot settings (enabled, required)
Form fields and validation
AI features and settings
Allowed domains (CORS)

Runtime Customization

Pre-fill User Data

Pre-fill the form with the current user's information:

IssueCapture.init({
  apiKey: 'your_api_key',
  user: {
    name: 'John Doe',
    email: 'john@example.com'
  }
});

Tip: If you have user authentication, dynamically pass the logged-in user's details.

Custom Trigger

Specify a custom button or element to trigger the widget:

IssueCapture.init({
  apiKey: 'your_api_key',
  trigger: '.feedback-button'  // Any CSS selector
});

Note: Without a trigger, you'll need to open the widget programmatically using IssueCapture.open()

Set Field Defaults

Programmatically set default values for priority, component, labels, and custom fields:

IssueCapture.init({
  apiKey: 'your_api_key',
  trigger: '#bug-button',
  defaultValues: {
    priority: 'High',              // Set default priority
    component: 'Frontend',         // Set default component
    labels: ['bug', 'ui'],         // Pre-select labels
    customFields: {                // Set custom field values
      'customfield_10001': 'Production'
    }
  }
});

Use Case: Great for setting context-based defaults like priority based on user role, or component based on current page section.

Custom Fields

Add custom Jira fields to your issue submission form. IssueCapture automatically fetches field options from Jira.

How It Works

Dashboard Setup - Go to your widget's Form Configuration page
Click "Add Custom Field" - Fetches available fields from your Jira project
Select Field - Choose from dropdown fields, text fields, multi-selects, etc.
Configure - Set placeholder text, help text, and required status
Save - Field appears in the widget form with all options from Jira

Supported Field Types

Text Fields

• Single-line text
• Multi-line textarea
• Number input

Selection Fields

• Single select dropdown
• Multi-select checkboxes
• Radio buttons

Special Fields

• Date picker
• Checkbox (boolean)
• User picker (text input)

Automatic Features

• Options fetched from Jira
• Required field validation
• Default values support

Setting Default Values Programmatically

Pre-fill custom field values when initializing the widget:

IssueCapture.init({
  apiKey: 'your_api_key',
  defaultValues: {
    customFields: {
      'customfield_10001': 'Critical',     // Single select (Urgency)
      'customfield_10002': 'v2.1.0',       // Text field (Version)
      'customfield_10003': ['Tag1', 'Tag2'] // Multi-select
    }
  }
});

Note: Field IDs (like customfield_10001) must match exactly what Jira uses. Find them in your dashboard when adding custom fields.

Example: Environment Field

A common use case is adding an "Environment" dropdown:

// Auto-detect environment and set as default
const getEnvironment = () => {
  if (window.location.hostname === 'localhost') return 'Development';
  if (window.location.hostname.includes('staging')) return 'Staging';
  return 'Production';
};

IssueCapture.init({
  apiKey: 'your_api_key',
  defaultValues: {
    customFields: {
      'customfield_10050': getEnvironment()  // Environment field
    }
  }
});

Pro Tip

Custom fields with dropdown options automatically show all available values from Jira. Users can select from these options without needing to know the exact values.

API Reference

IssueCapture.init(config)

Initialize the IssueCapture widget with your configuration.

Parameters:

config (Object) - Configuration object

Returns:

void

IssueCapture.init({
  apiKey: 'your_api_key'
});

IssueCapture.open()

Programmatically open the widget modal.

Returns:

void

// Open widget on button click
document.getElementById('custom-button').addEventListener('click', () => {
  IssueCapture.open();
});

IssueCapture.close()

Programmatically close the widget modal.

Returns:

void

IssueCapture.close();

Events

Listen to widget events with callbacks:

onSubmit

Called when an issue is successfully submitted.

IssueCapture.init({
  apiKey: 'your_api_key',
  onSubmit: function(data) {
    console.log('Issue submitted:', data);
    // data contains: issueId, summary, description, etc.
  }
});

onOpen / onClose

Track when users open or close the widget.

IssueCapture.init({
  apiKey: 'your_api_key',
  onOpen: function() {
    console.log('Widget opened');
    // Track analytics, show help text, etc.
  },
  onClose: function() {
    console.log('Widget closed');
  }
});

onError

Handle errors gracefully.

IssueCapture.init({
  apiKey: 'your_api_key',
  onError: function(error) {
    console.error('IssueCapture error:', error);
    // Show custom error message
  }
});

Custom Styling

Customize your widget's appearance with CSS. IssueCapture uses Shadow DOM isolation, so your custom CSS won't affect your website.

Dashboard Theme Editor

The easiest way to customize your widget is through the dashboard:

Go to Widgets → Your Widget → Theme
Choose from preset themes (Default, Dark, Minimal, etc.)
Customize colors, border radius, and font family
Add custom CSS for advanced styling
Preview changes in real-time

Available CSS Selectors

Use these CSS selectors to target specific parts of the widget:

/* Main Widget Container */
.issuecapture-modal { }              /* Main modal wrapper */
.issuecapture-backdrop { }           /* Background overlay */

/* Modal Structure */
.issuecapture-header { }             /* Modal header */
.issuecapture-header h2 { }          /* Modal title text */
.issuecapture-close { }              /* Close button */
.issuecapture-content { }            /* Modal body/content */

/* Form Elements */
.issuecapture-form-group { }         /* Form field wrapper */
.issuecapture-label { }              /* Field labels */
.issuecapture-input { }              /* Text inputs */
.issuecapture-textarea { }           /* Text areas */
.issuecapture-select { }             /* Select dropdowns */

/* Buttons */
.issuecapture-btn { }                /* All buttons */
.issuecapture-btn-primary { }        /* Primary action buttons */
.issuecapture-btn-secondary { }      /* Secondary buttons */
.issuecapture-btn-ghost { }          /* Ghost/outline buttons */

/* States */
.issuecapture-success { }            /* Success screen */
.issuecapture-loading { }            /* Loading state */
.issuecapture-spinner { }            /* Loading spinner */

/* Screenshot Capture */
.issuecapture-screenshot-capture { } /* Screenshot step container */
.issuecapture-screenshot-title { }   /* Screenshot step title */

Example: Custom Button Styling

Add a gradient background to the submit button:

.issuecapture-btn-primary {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
  border-radius: 25px !important;
  font-weight: 600 !important;
  text-transform: uppercase !important;
  letter-spacing: 0.5px !important;
}

Example: Custom Input Styling

Add custom focus effects to form inputs:

.issuecapture-input,
.issuecapture-textarea {
  border: 2px solid #e0e0e0 !important;
  transition: all 0.3s ease !important;
}

.issuecapture-input:focus,
.issuecapture-textarea:focus {
  border-color: #667eea !important;
  box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.2) !important;
}

Example: Larger Modal

Make the widget modal larger:

.issuecapture-modal {
  max-width: 800px !important;
  width: 95% !important;
}

Example: Dark Theme Customization

Further customize the dark theme preset:

/* Custom dark theme tweaks */
.issuecapture-modal {
  background: #0f0f0f !important;
  border: 1px solid #333 !important;
}

.issuecapture-input,
.issuecapture-textarea {
  background: #1a1a1a !important;
  border-color: #444 !important;
  color: #f0f0f0 !important;
}

.issuecapture-label {
  color: #b0b0b0 !important;
}

Important Notes:

• Use !important to override default styles
• CSS is sanitized for security - JavaScript and dangerous patterns are blocked
• Shadow DOM isolation means your CSS won't affect your website
• Test your custom CSS in the dashboard preview before saving

CSS Validation

The dashboard includes real-time CSS validation that checks for syntax errors, security issues, and provides warnings for potentially problematic patterns. Invalid CSS cannot be saved.

Need help?