Skip to main content
Version: Isle Royale (2.5.0)

Display Options

Display options control how the ToughClicks library renders and behaves in your application. These options must be set after initializing the library and before rendering the agreements.

Overview​

Display options are configured by calling setDisplayOptions() on your ToughClicks instance with an options object. This configuration determines:

  • Where agreements are rendered
  • How agreements are displayed
  • How users are identified
  • Whether modals are used for viewing terms
  • Whether acceptance is automatic or manual

Setting Display Options​

const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);

const options = {
containerId: 'tc-container',
displayMethod: 'Individual',
signerIdSelector: 'email-input',
shouldOpenModal: true,
manualAcceptance: false
};

tc.setDisplayOptions(options);

Required Fields​

containerId​

Type: string

The HTML ID of the container element where ToughClicks will render the agreement interface.

const options = {
containerId: 'tc-container',
// ... other options
};

The container should exist in your DOM before calling setDisplayOptions():

<div id="tc-container"></div>

displayMethod​

Type: 'Scroll' | 'Individual' | 'Group' | 'buttonAssent'

Controls how agreements are displayed and what actions users must perform to accept terms.

  • 'Scroll': Shows full terms in scrollable containers; checkboxes disabled until user scrolls to bottom
  • 'Individual': Shows a checkbox for each document; each click is a discrete agreement
  • 'Group': Shows a single checkbox for all documents; one click accepts all terms
  • 'buttonAssent': Shows a notice and no checkbox; clicking your own submit button is the agreement. Requires assentActionLabel

See Display Methods for detailed information about each method.

const options = {
displayMethod: 'Individual',
// ... other options
};

Signer Identification (One Required)​

You must provide one and only one of these fields to identify the signer.

signerIdSelector​

Type: string

The HTML ID of a form input field that the signer will enter their unique identifier into. ToughClicks will listen to changes in this field to populate the signer identifier.

When to use:

  • You have a form where users enter identifying information
  • The identifier is collected as part of your existing form flow
  • Users enter their email, username, or other identifier
const options = {
signerIdSelector: 'email-input',
// ... other options
};
<input type="email" id="email-input" placeholder="Enter your email" />

signerId​

Type: string

A signer identifier supplied directly to ToughClicks, bypassing form input.

When to use:

  • You're using a UUID or internal user ID
  • The integration occurs after user sign-in
  • You already have the user's identifier in your application state
const options = {
signerId: user.id, // e.g., "user-uuid-1234"
// ... other options
};
info

If you're using a UUID, we recommend also setting the signer's email address using setSignerEmailAddress() to make it easier to search for agreements in the ToughClicks dashboard. See Signer Identifiers for more information.

Optional Fields​

shouldOpenModal​

Type: boolean Default: false

Controls whether document terms open in a modal dialog or in a new browser tab.

  • true: Opens terms in a customizable modal overlay
  • false: Opens terms in a new browser tab
const options = {
shouldOpenModal: true,
// ... other options
};

When enabled, you can customize the modal's appearance using CSS classes. See CSS Customization for styling options.

assentActionLabel​

Type: string Required when displayMethod is 'buttonAssent', ignored otherwise.

The label of your own submit button, substituted into the notice so the sentence names the exact control the visitor presses.

const options = {
displayMethod: 'buttonAssent',
assentActionLabel: 'Complete Booking',
// ... other options
};

Renders as: By clicking Complete Booking you agree to our Booking Agreement.

Match your button's label exactly, including capitalization: the label is stored on the acceptance record and printed on the certificate, so a mismatch between the notice and the button weakens the record.

You can also set this per packet in the Management Portal, which lets your legal team change the wording without a deploy. A value supplied here takes precedence.

If you select 'buttonAssent' without a label from either source, the SDK reports a MISSING_ASSENT_ACTION_LABEL validation error rather than rendering a sentence with no verb.

assentActionSelector​

Type: string Optional, and only used when displayMethod is 'buttonAssent'. Strongly recommended.

A CSS selector for your submit button. When supplied, the SDK measures the button's position and size at acceptance time alongside the notice's, which evidences that the notice was adjacent to the action.

const options = {
displayMethod: 'buttonAssent',
assentActionLabel: 'Complete Booking',
assentActionSelector: '#checkout-submit',
// ... other options
};

Without it, the acceptance certificate can show that the notice was on screen but not how close it was to the button. If the selector matches nothing, or is not a valid selector, the measurement is recorded as absent and acceptance proceeds normally.

manualAcceptance​

Type: boolean Default: false

Controls whether acceptance records are created automatically or manually.

  • false: Automatic - acceptance created when all checkboxes are checked and valid user ID is set
  • true: Manual - you must call tc.accept() to create acceptance
const options = {
manualAcceptance: true,
// ... other options
};

When set to true, you'll need to manually trigger acceptance:

// Listen for validation state
tc.on('tc-valid', (e) => {
if (e.detail.isValid) {
// Enable your submit button
submitButton.disabled = false;
}
});

// Manually accept when user submits
submitButton.addEventListener('click', async () => {
const success = await tc.accept();
if (success) {
// Proceed with your application flow
}
});

See Manual Acceptance for complete documentation.

Complete Configuration Examples​

Basic Email Collection​

const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);

const options = {
containerId: 'tc-container',
displayMethod: 'Individual',
signerIdSelector: 'email-input'
};

tc.setDisplayOptions(options);

Post-Login with UUID​

const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);

const options = {
containerId: 'tc-container',
displayMethod: 'Group',
signerId: currentUser.uuid
};

tc.setDisplayOptions(options);

// Optionally set email for searchability
tc.setSignerEmailAddress(currentUser.email);
const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);

const options = {
containerId: 'tc-container',
displayMethod: 'Scroll',
signerIdSelector: 'email-input',
shouldOpenModal: true,
manualAcceptance: true
};

tc.setDisplayOptions(options);

// Handle validation state
tc.on('tc-valid', (e) => {
document.getElementById('submit-btn').disabled = !e.detail.isValid;
});

// Handle manual acceptance
document.getElementById('submit-btn').addEventListener('click', async () => {
const success = await tc.accept();
if (success) {
window.location.href = '/dashboard';
}
});

// Handle acceptance completion
tc.on('tc-accepted', (e) => {
console.log('All documents accepted:', e.detail);
});

Code vs Management Portal​

Display options can be configured in two places:

  1. In your code - using setDisplayOptions() (recommended for production)
  2. In the ToughClicks Management Portal - as default packet settings

Important: Settings in your code take precedence over Management Portal settings. This ensures configuration changes in the web app don't cause unintended consequences in your production application.

Validation​

The library will validate your options and throw errors if:

  • Required fields are missing
  • Both signerId and signerIdSelector are provided
  • Neither signerId nor signerIdSelector is provided
  • displayMethod has an invalid value
  • containerId references a non-existent DOM element
  • displayMethod is 'buttonAssent' and no assentActionLabel is available from the display options or the packet configuration
  • displayMethod is 'buttonAssent' and optional: true is set. With no checkbox there is no way for a visitor to decline, so an optional packet would silently become required