Attribute System - Attributes by Finsweet

Attribute Naming Convention

All Attributes by Finsweet follow a consistent naming pattern: fs-{solution}-{role}="{value}"

Pattern Breakdown

fs-accordion-element="item"
│  │         │        │
│  │         │        └─ Value: Specific configuration or identifier
│  │         └────────── Role: Element's function within the solution
│  └──────────────────── Solution: The attribute solution name
└─────────────────────── Prefix: Finsweet namespace

The `fs-` Prefix

The fs- prefix serves multiple purposes:

Namespace: Prevents conflicts with native HTML attributes or other libraries
Detection: The core library scans for attributes matching /^fs-([^-]+)/ pattern
Recognition: Developers instantly recognize Finsweet attributes in markup

// From packages/attributes/src/attributes.ts:103-104
const fsMatch = name.match(/^fs-([^-]+)/);
const key = fsMatch?.[1] as FinsweetAttributeKey | undefined;

The core library only looks at the first segment after fs- to determine which attribute solution to load. For example, fs-accordion-element, fs-accordion-target, and fs-accordion-header all trigger loading of the accordion attribute.

Attribute Solutions

Each attribute solution corresponds to a specific package. The solution name comes directly after the fs- prefix:

Available Solutions

// From packages/utils/src/constants/attributes.ts
export const ACCORDION_ATTRIBUTE = 'accordion';
export const AUTO_VIDEO_ATTRIBUTE = 'autovideo';
export const CODE_HIGHLIGHT_ATTRIBUTE = 'codehighlight';
export const COMBO_BOX_ATTRIBUTE = 'combobox';
export const COPY_CLIP_ATTRIBUTE = 'copyclip';
export const DISPLAY_VALUES_ATTRIBUTE = 'displayvalues';
export const FAV_CUSTOM_ATTRIBUTE = 'favcustom';
export const FORM_SUBMIT_ATTRIBUTE = 'formsubmit';
export const INPUT_ACTIVE_ATTRIBUTE = 'inputactive';
export const INPUT_COUNTER_ATTRIBUTE = 'inputcounter';
export const LIST_ATTRIBUTE = 'list';
export const MIRROR_CLICK_ATTRIBUTE = 'mirrorclick';
export const MIRROR_INPUT_ATTRIBUTE = 'mirrorinput';
export const MODAL_ATTRIBUTE = 'modal';
export const NUMBER_COUNT_ATTRIBUTE = 'numbercount';
export const QUERY_PARAM_ATTRIBUTE = 'queryparam';
export const RANGE_SLIDER_ATTRIBUTE = 'rangeslider';
export const READ_TIME_ATTRIBUTE = 'readtime';
export const REMOVE_QUERY_ATTRIBUTE = 'removequery';
export const SCROLL_DISABLE_ATTRIBUTE = 'scrolldisable';
export const SELECT_CUSTOM_ATTRIBUTE = 'selectcustom';
export const SLIDER_DOTS_ATTRIBUTE = 'sliderdots';
export const SMART_LIGHTBOX_ATTRIBUTE = 'smartlightbox';
export const SOCIAL_SHARE_ATTRIBUTE = 'socialshare';
export const STAR_RATING_ATTRIBUTE = 'starrating';
export const TOC_ATTRIBUTE = 'toc';
export const VIDEO_HLS_ATTRIBUTE = 'videohls';

Each solution maps to a package: @finsweet/attributes-{solution}

Roles and Elements

The role segment defines what function an element serves within the attribute solution.

Common Role Patterns

Component Elements

<!-- Main component wrapper -->
<div fs-accordion-element="component">
  <!-- Individual items -->
  <div fs-accordion-element="item">
    <button fs-accordion-element="trigger">Toggle</button>
    <div fs-accordion-element="content">Hidden content</div>
  </div>
</div>

Triggers and Targets

<!-- Element that triggers action -->
<button fs-modal-element="trigger" fs-modal-target="login">
  Open Modal
</button>

<!-- Element that receives action -->
<div fs-modal-element="modal" fs-modal-modal="login">
  Modal content
</div>

Configuration Attributes

<!-- Behavioral configuration -->
<div 
  fs-list-element="component"
  fs-list-empty="No items found"
  fs-list-pagesize="10"
>
  <!-- List items -->
</div>

Role Naming Conventions

Roles typically follow these patterns:

element: Defines the type of component ("component", "item", "trigger", etc.)
target: Identifies which instance to interact with (often matches with a corresponding identifier)
Configuration keys: Named after the setting they control ("pagesize", "empty", "duration", etc.)

Attribute Values

Value Types

1. Identifiers

Used to connect related elements:

<button fs-modal-element="trigger" fs-modal-target="signup">
  Sign Up
</button>

<div fs-modal-element="modal" fs-modal-modal="signup">
  <!-- Modal content -->
</div>

Both use "signup" as an identifier to connect the trigger and modal.

2. Element Types

Define the role an element plays:

<div fs-accordion-element="component">
  <div fs-accordion-element="item">
    <button fs-accordion-element="trigger">Header</button>
    <div fs-accordion-element="content">Body</div>
  </div>
</div>

3. Configuration Values

Provide settings or data:

<!-- Numbers -->
<div fs-list-pagesize="10"></div>

<!-- Strings -->
<div fs-list-empty="No results"></div>

<!-- Booleans -->
<div fs-list-show="true"></div>

Boolean attributes in HTML can be represented as:

attribute="true" or attribute="false" (explicit)
Presence = true, absence = false (implicit)

Different attributes may use different conventions. Check the specific attribute documentation.

4. JSON Values

Complex configurations can use JSON:

<div fs-list-filters='{"category": "news", "limit": 5}'></div>

When using JSON in HTML attributes, use single quotes for the attribute value and double quotes for JSON keys and string values.

Attribute Detection

Core Library Detection

The core library detects attributes using a regex pattern:

// From packages/attributes/src/attributes.ts:103
const fsMatch = name.match(/^fs-([^-]+)/);

This regex:

Matches attributes starting with fs-
Captures the first segment (the solution name)
Ignores everything after the second hyphen

Detection Process

Valid Attribute Detection

The library validates detected attributes against a known set:

// From packages/attributes/src/attributes.ts:14
const ATTRIBUTE_KEYS = new Set(Object.values(ATTRIBUTES));

// From packages/attributes/src/attributes.ts:106-108
if (key && ATTRIBUTE_KEYS.has(key)) {
  usedAttributes.add(key);
}

Unknown fs-* attributes are ignored, preventing errors from:

Typos in attribute names
Custom attributes using the fs- prefix
Removed or deprecated attributes

Attribute Structure Example

Here’s a complete example showing the attribute system in action:

<!-- Accordion Component -->
<div fs-accordion-element="component">
  
  <!-- First accordion item -->
  <div fs-accordion-element="item">
    <button fs-accordion-element="trigger">
      What is Attributes by Finsweet?
    </button>
    <div fs-accordion-element="content">
      <p>Attributes is a library of JavaScript utilities...</p>
    </div>
  </div>

  <!-- Second accordion item -->
  <div fs-accordion-element="item">
    <button fs-accordion-element="trigger">
      How does it work?
    </button>
    <div fs-accordion-element="content">
      <p>It uses HTML attributes to add functionality...</p>
    </div>
  </div>

</div>

Breakdown:

Solution: accordion - Loads @finsweet/attributes-accordion
Roles:
- element="component" - The wrapper container
- element="item" - Individual accordion items
- element="trigger" - Clickable headers
- element="content" - Expandable content areas
Values: Define the element type within the solution

Best Practices

1. Use Semantic HTML

<!-- Good: Semantic button -->
<button fs-accordion-element="trigger">Toggle</button>

<!-- Avoid: Non-semantic div -->
<div fs-accordion-element="trigger">Toggle</div>

2. Keep Attribute Names Lowercase

<!-- Good -->
<div fs-modal-target="login"></div>

<!-- Bad: Will not work -->
<div fs-Modal-Target="login"></div>

HTML attributes are case-insensitive, but the library expects lowercase.

3. Use Consistent Identifiers

<!-- Good: Matching identifiers -->
<button fs-modal-target="signup">Open</button>
<div fs-modal-modal="signup">Content</div>

<!-- Bad: Mismatched identifiers -->
<button fs-modal-target="signup">Open</button>
<div fs-modal-modal="sign-up">Content</div>

4. Avoid Attribute Conflicts

Don’t mix multiple solutions on the same element unless documented:

<!-- Usually avoid this -->
<div 
  fs-accordion-element="item" 
  fs-modal-element="modal"
>
  <!-- May cause unexpected behavior -->
</div>

5. Validate Attribute Values

Check documentation for expected values:

<!-- Correct -->
<div fs-list-pagesize="10"></div>

<!-- Incorrect: String instead of number -->
<div fs-list-pagesize="ten"></div>

TypeScript Types

For TypeScript users, attribute keys are typed:

// From packages/utils/src/types/core.ts:5
export type FinsweetAttributeKey = 
  (typeof ATTRIBUTES)[keyof typeof ATTRIBUTES];

// Usage
const loadAccordion = (key: FinsweetAttributeKey) => {
  window.FinsweetAttributes.load(key);
};

loadAccordion('accordion'); // ✓ Valid
loadAccordion('invalid');   // ✗ Type error

Debugging Attributes

Use the browser console to inspect detected attributes:

// Check which attributes are loaded
console.log(window.FinsweetAttributes.modules);

// Check which attributes are currently running
console.log(window.FinsweetAttributes.process);

// Check library version
console.log(window.FinsweetAttributes.version);

The window.FinsweetAttributes object is available immediately after the core library loads. You can inspect it at any time to debug attribute loading and execution.

Documentation Index

​Attribute Naming Convention

​Pattern Breakdown

​The fs- Prefix

​Attribute Solutions

​Available Solutions

​Roles and Elements

​Common Role Patterns

​Component Elements

​Triggers and Targets

​Configuration Attributes

​Role Naming Conventions

​Attribute Values

​Value Types

​1. Identifiers

​2. Element Types

​3. Configuration Values

​4. JSON Values

​Attribute Detection

​Core Library Detection

​Detection Process

​Valid Attribute Detection

​Attribute Structure Example

​Breakdown:

​Best Practices

​1. Use Semantic HTML

​2. Keep Attribute Names Lowercase

​3. Use Consistent Identifiers

​4. Avoid Attribute Conflicts

​5. Validate Attribute Values

​TypeScript Types

​Debugging Attributes

Attribute Naming Convention

Pattern Breakdown

The `fs-` Prefix

Attribute Solutions

Available Solutions

Roles and Elements

Common Role Patterns

Component Elements

Triggers and Targets

Configuration Attributes

Role Naming Conventions

Attribute Values

Value Types

1. Identifiers

2. Element Types

3. Configuration Values

4. JSON Values

Attribute Detection

Core Library Detection

Detection Process

Valid Attribute Detection

Attribute Structure Example

Breakdown:

Best Practices

1. Use Semantic HTML

2. Keep Attribute Names Lowercase

3. Use Consistent Identifiers

4. Avoid Attribute Conflicts

5. Validate Attribute Values

TypeScript Types

Debugging Attributes