Adaptive Density Mode

Quick start guide and documentation

Quick Start (3 Steps)

Get adaptive density working in under 3 minutes.

1 Include the CSS and JS

Code • HTML

2 Create Your Layout

Code • HTML




    
Content 1

    
Content 2

    
Content 3

3 Done!

✓ That's it! Your layout will now automatically adjust density based on whether the user has a touch screen (spacious) or mouse (compact). View on different devices to see it in action!

Density Levels

Three levels of spacing are available:

Level Gap Padding Use Case
Compact 0.75rem 0.5rem Fine pointers (mouse, trackpad) - maximizes screen space
Standard 1rem 1rem Default - balanced spacing for all devices
Spacious 1.5rem 1.5rem Coarse pointers (touch) - easier touch targeting
Tip: The system automatically detects pointer type on page load. Touch devices get spacious, mouse devices get compact, with standard as the fallback.

Manual Override

Override automatic detection with the data-rsl-density attribute.

Via HTML Attribute

Code • HTML




    
Item 1

    
Item 2

    
Item 3

    
Item 4







    
Item 1

    
Item 2

    
Item 3

Via CSS Class

Code • HTML



    
Compact spacing






    
Spacious spacing

Via JavaScript API

Code • JavaScript

// Get the layout element
const layout = document.querySelector('.slot-layout');

// Set density manually
RSL.Density.set(layout, 'compact');

// Get current density
const current = RSL.Density.get(layout);
console.log(current); // 'compact'

// Reset to auto-detect mode
RSL.Density.reset(layout);

Integration with RSL Features

Balanced Layout (Masonry)

Density automatically affects gaps in balanced layouts.

Code • HTML



    
Item 1

    
Item 2

    
Item 3
Note: When changing density programmatically on balanced layouts, trigger a rebuild:

RSL.Density.set(layout, 'compact');
RSL.initBalancedSlots();

Sidebar Layout

Sidebar margins adapt to the active density level.

Code • HTML



    
    

        Main content

Nested Layouts

Apply density to parent containers to affect all nested layouts.

Code • HTML




    

        

            

                
Nested 1

                
Nested 2

            

        

        
Item 2

JavaScript API Reference

Method Description
RSL.Density.init() Initialize or re-initialize density detection for all layouts
RSL.Density.set(element, density) Set density for a specific element ('compact', 'standard', or 'spacious')
RSL.Density.get(element) Get current density level of an element
RSL.Density.reset(element) Reset element to auto-detect mode
RSL.Density.detectPointer() Detect current pointer type ('fine', 'coarse', or 'none')
RSL.Density.levels Object containing available density levels

Complete API Example

Code • JavaScript

// Detect pointer type
const pointerType = RSL.Density.detectPointer();
console.log('Pointer type:', pointerType);
// Output: 'fine' (mouse) or 'coarse' (touch)

// Get available density levels
console.log(RSL.Density.levels);
// Output: { COMPACT: 'compact', STANDARD: 'standard', SPACIOUS: 'spacious' }

// Get element
const layout = document.querySelector('.slot-layout');

// Get current density
const currentDensity = RSL.Density.get(layout);
console.log('Current density:', currentDensity);

// Set density
RSL.Density.set(layout, RSL.Density.levels.SPACIOUS);

// Reset to auto-detect
RSL.Density.reset(layout);

// Re-initialize all layouts (useful after dynamic content)
RSL.Density.init();

CSS Variables

Customize density values by overriding CSS variables:

Variable Default Compact Default Standard Default Spacious
--density-*-gap 0.75rem 1rem 1.5rem
--density-*-padding 0.5rem 1rem 1.5rem
--density-*-item-padding 0.75rem 1rem 1.5rem
--density-*-sidebar-margin 1rem 1.5rem 2rem

Custom Density Values

Code • CSS

:root {
  /* Override compact density */
  --density-compact-gap: 0.5rem;
  --density-compact-padding: 0.25rem;

  /* Override spacious density */
  --density-spacious-gap: 2rem;
  --density-spacious-padding: 2rem;
}

Accessibility Features

Automatic Adjustments

  • prefers-reduced-motion: Disables all transitions and animations
  • prefers-contrast: more: Increases spacing for better readability
  • Touch targets: Spacious mode ensures minimum 44x44px tap targets
Best Practice: Always test your layouts with different density levels to ensure content remains accessible and touch targets remain adequately sized.

Troubleshooting

Density not changing automatically

  • Ensure density.js is loaded after grid.css and density.css
  • Check browser console for JavaScript errors
  • Verify that layouts have appropriate classes (.slot-layout, etc.)

Manual override not working

  • Check that data-rsl-density value is correct ('compact', 'standard', or 'spacious')
  • Ensure density.css is loaded and not overridden by other styles
  • Use browser DevTools to inspect CSS variable values

Spacing looks wrong on certain elements

  • Verify that parent container has density attribute applied
  • Check for conflicting CSS that overrides gap or padding
  • Ensure you're using var(--rsl-gap) instead of hard-coded values

Next Steps

See It In Action

Open density.html in your browser

Copy Examples

Use playground.html as a template

Customize

Override CSS variables to match your design system

Back to Examples