OAK UI · FilterCraft

Cos'è e a cosa serve FilterCraft

FilterCraft è un plugin JavaScript Vanilla che filtra dinamicamente elementi HTML in base a categorie definite dall'utente. È progettato per essere leggero, veloce e facile da integrare.

È ideale per portfolio, gallerie, liste di prodotti, articoli, showcase di progetti o qualsiasi sezione di contenuti che necessita di filtri interattivi.

Gli sviluppatori possono integrarlo in pochi minuti senza framework aggiuntivi, grazie alla sua API semplice e intuitiva.

Il plugin gestisce automaticamente:

• Selezione dei pulsanti di filtro - Rileva automaticamente gli elementi con classe `.filtercraft__button_filter`
• Gestione degli elementi filtrabili - Controlla la visibilità degli elementi con classe `.filtercraft__item`
• Aggiornamento dinamico del titolo - Modifica automaticamente il contenuto di `.filtercraft__elements_title` (opzionale)
• Supporto multi-categoria - Gli elementi possono appartenere a più categorie contemporaneamente
• Animazioni fluide - Usa classi CSS e `requestAnimationFrame` per transizioni performanti
• Istanze multiple - È possibile inizializzare più filtri sulla stessa pagina

Grazie alla sua struttura modulare e al fatto che non altera il DOM in modo distruttivo, FilterCraft è performante anche su liste di grandi dimensioni.

Perché scegliere FilterCraft

• Zero dipendenze - Funziona con JavaScript puro, senza librerie esterne
• Leggero e veloce - Solo pochi KB di codice, ottimizzato per le performance
• Configurazione immediata - Parametri personalizzabili tramite oggetto options
• Compatibilità cross-browser - Safari, Firefox, Chrome, Edge e Opera
• Istanze multiple - Più filtri nella stessa pagina
• Manutenzione semplificata - File .js e .css pronti all'uso
• SEO-friendly - Non altera il DOM in modo distruttivo

Come installarlo

1. Inclusione dei file

Scarica i file minificati e includili nella tua pagina:

<link rel="stylesheet" href="./dist/FilterCraft-min.css">
<script src="./dist/FilterCraft-min.js"></script>

Oppure includi i file da CDN:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/davidemancuso/oak-ui-filtercraft@1.0.0/dist/FilterCraft-min.css">
<script src="https://cdn.jsdelivr.net/gh/davidemancuso/oak-ui-filtercraft@1.0.0/dist/FilterCraft-min.js"></script>

2. Struttura HTML

Crea la struttura HTML con i pulsanti di filtro e gli elementi da filtrare:

<div class="filtercraft">
  <div role="tablist" aria-label="Filtri contenuti">
    <button class="filtercraft__button_filter active" type="button" data-category="all">Tutti</button>
    <button class="filtercraft__button_filter" type="button" data-category="web">Web</button>
    <button class="filtercraft__button_filter" type="button" data-category="mobile">Mobile</button>
    <button class="filtercraft__button_filter" type="button" data-category="design">Design</button>
  </div>

  <h2 class="filtercraft__elements_title"></h2>

  <div>
    <div class="filtercraft__item" data-category="web">Progetto Web 1</div>
    <div class="filtercraft__item" data-category="mobile">App Mobile 1</div>
    <div class="filtercraft__item" data-category="web,mobile">Progetto Multi-piattaforma</div>
    <div class="filtercraft__item" data-category="design">Design 1</div>
  </div>
</div>

3. Inizializzazione

Inizializza il plugin con le opzioni di default:

<script>
// Inizializzazione base
let myFilter = new FilterCraft();

// Oppure con opzioni personalizzate
let myFilter = new FilterCraft({
    AllDataName: 'tutti',
    ContainerClass: '.filtercraft',
    ButtonsItemClass: '.filtercraft__button_filter',
    ElementsItemClass: '.filtercraft__item',
    TitleElementClass: '.filtercraft__elements_title',
    AnimationDuration: '300'
});
</script>

Opzioni di configurazione

FilterCraft accetta un oggetto di opzioni per personalizzare il comportamento:

Esempi pratici

Portfolio di progetti

<div class="filtercraft">
  <div role="tablist" aria-label="Filtri portfolio">
    <button class="filtercraft__button_filter active" type="button" data-category="all">Tutti i progetti</button>
    <button class="filtercraft__button_filter" type="button" data-category="frontend">Frontend</button>
    <button class="filtercraft__button_filter" type="button" data-category="backend">Backend</button>
    <button class="filtercraft__button_filter" type="button" data-category="mobile">Mobile</button>
  </div>

  <h2 class="filtercraft__elements_title">Tutti i progetti</h2>

  <div>
    <article class="filtercraft__item" data-category="frontend">
        <h3>Sito E-commerce</h3>
        <p>Progetto React con TypeScript</p>
    </article>
    <article class="filtercraft__item" data-category="backend">
        <h3>API REST</h3>
        <p>Backend Node.js con Express</p>
    </article>
    <article class="filtercraft__item" data-category="frontend,mobile">
        <h3>App PWA</h3>
        <p>Applicazione web progressiva</p>
    </article>
  </div>
</div>

Galleria di immagini

<div class="filtercraft">
  <div role="tablist" aria-label="Filtri galleria">
    <button class="filtercraft__button_filter active" type="button" data-category="all">Tutte le foto</button>
    <button class="filtercraft__button_filter" type="button" data-category="nature">Natura</button>
    <button class="filtercraft__button_filter" type="button" data-category="urban">Urbano</button>
    <button class="filtercraft__button_filter" type="button" data-category="portrait">Ritratti</button>
  </div>

  <h2 class="filtercraft__elements_title">Tutte le foto</h2>

  <div>
    <div class="filtercraft__item" data-category="nature">
        <img src="forest.jpg" alt="Foresta">
    </div>
    <div class="filtercraft__item" data-category="urban">
        <img src="city.jpg" alt="Città">
    </div>
    <div class="filtercraft__item" data-category="nature,urban">
        <img src="park.jpg" alt="Parco urbano">
    </div>
  </div>
</div>

Accessibilità

FilterCraft non impone markup specifico: puoi usare markup semantico e attributi ARIA (ad esempio role="tablist" e aria-label) senza interferenze. Per l'accessibilità, ti consiglio di:

• Usare <button> per i filtri con etichette testuali chiare
• Rendere visibile lo stato attivo con uno stile ben distinguibile
• Associare un titolo aggiornato per comunicare il filtro attivo

CSS (stato attivo)

Le animazioni sono già incluse in FilterCraft-min.css. Se vuoi personalizzare lo stato attivo dei pulsanti, puoi partire da questo snippet:

/* Pulsanti attivi */
.filtercraft__button_filter.active {
    background-color: #007cba;
    color: #fff;
}