Jump to Navigation Jump to Main Content Jump to Footer
Home » Docs » Features » Ready‑made components

Ready‑made components

Chisel comes with a library of reusable, production‑ready components. The theme ships with structured Twig partials and scoped SCSS that let you assemble navigation, titles, sidebars, icons, and common UI patterns without starting from scratch. Each component follows the theme’s ITCSS/BEM conventions, so styles remain predictable and easy to extend.
Under the hood, inc/WP/Components.php provides helper methods and pre‑prepared data for menus, titles, widgets, and icons, which are added to the Timber context and available in any Twig view. UI pieces in views/components/ and views/objects/ render clean markup, while src/styles/components/ keeps presentation consistent across the site.

Overview

All reusable UI pieces live under views/components/ and can be included from any Twig template. Most components are BEM‑styled and rely on small helper functions like bem().

Key directories:

  • views/components/ — main component library
  • views/partials/ — small partials and utilities
  • views/objects/ — low-level UI objects (e.g., icons)
  • src/styles/components/ — SCSS/CSS for components
  • src/scripts/editor/components/ — editor‑specific JS components

Core components and expected context

  • the-title
    • Path: views/components/the-title.twig
    • Usage: outputs a post/page title. Works with global post context.
  • logo
    • Path: views/components/logo.twig
    • Context:
      • site (global Timber site, provides site.link, site.title)
      • Site logo (HTML/SVG/markup)
    • Include:
{% include 'components/main-nav.twig' %}
Twig
  • main-nav
    • Path: views/components/main-nav.twig
    • Pulls menu by slug: get_nav_menu('main_nav')
    • Supports mega-menu via menu meta:
      • mega_menu_enable, mega_menu_columns
    • Renders items via components/main-nav-item.twig
    • Notes:
      • Up to 3 levels supported
      • Mega menu: add c-main-nav--columns and has-{2|3|4}-columns via meta
    • Include:
{% include 'components/main-nav.twig' %}
Twig
  • post-item
    • Path: views/components/post-item.twig
    • Context: post (TimberPost or compatible)
    • Outputs title, meta, excerpt, tags, thumbnail
    • Include:
{% include 'components/post-item.twig' with { post: post } %}
Twig
  • pagination
    • Path: views/components/pagination.twig
    • Modes:
      • Standard numbered pagination (uses posts.pagination)
      • “Load more” mode with AJAX
    • Context:
      • Required: posts (TimberPostQuery with pagination)
      • Optional “load more”:
        • type: 'load-more'
        • load_more: { post_type, per_page }
    • Include (standard or load more):
{% include 'components/pagination.twig' with { posts: posts } %}
Twig
{% include 'components/pagination.twig' with {
  posts: posts,
  type: 'load-more',
  load_more: { post_type: 'post', per_page: 6 }
} %}
Twig

The “load more” button integrates with the REST/AJAX endpoint load-more documented in ?REST API endpoints for AJAX requests .

  • slider (used in a Slider Block)
    • Path: views/components/slider.twig
    • Context:
      • params (raw config object) — processed by slider_prepare_params(params)
      • slides_html (rendered slides HTML; each slide must have swiper-slide class)
      • Optional class names: slider_container_class_names, slider_class_names
    • Include:
{% set slides %}
  <div class="swiper-slide">Slide 1</div>
  <div class="swiper-slide">Slide 2</div>
{% endset %}

{% include 'components/slider.twig' with {
  params: { type: 'default' },
  slides_html: slides,
  slider_container_class_names: 'my-slider-wrap',
  slider_class_names: 'my-slider'
} %}
Twig
  • Notes:
    • Markup expects Swiper.js CSS/JS on the page.
    • slider_prepare_params() adds data attributes and type modifiers.
  • header / footer
    • Paths: views/components/header.twig, views/components/footer.twig
    • Wrap site header/footer areas; typically used in views/base.twig.
  • main-nav-item
    • Path: views/components/main-nav-item.twig
    • Used internally by main-nav to render nested menu items.

Partials and objects

  • views/partials/block-edit-button.twig
    • Utility for showing a contextual “edit block” button in templates.
  • views/partials/icons-preview.twig
    • Preview of available icons.
  • views/objects/icon.twig
    • Low-level icon renderer. Pass icon name or SVG.

Usage patterns

  • Include a component:
{% include 'components/post-item.twig' with { post: post } %}n
Twig
  • Render a list of posts with items + pagination:
{% for post in posts %}
  {% include 'components/post-item.twig' with { post: post } %}
{% endfor %}

{% include 'components/pagination.twig' with { posts: posts } %}
Twig
  • Compile a component in PHP (if you need a string):
$html = Timber::compile('components/post-item.twig', array( 'post' => $post ) );
PHP

Conventions

  • BEM
    • Component classes start with c- (e.g., c-post-item, c-pagination)
    • Use the bem() Twig helper for block/element/modifier class composition
  • Data contracts
    • Each component expects minimal, clearly named variables
    • Pass only what the component needs (with { ... }) to keep templates clean
  • Extending
    • Create new components in views/components/ and co-locate styles in src/styles/components/
    • Reuse small “objects” from views/objects/ when building larger components

Bocks (as components)

In addition to Twig components in views/components/, the theme ships “blocks as components” that render consistent, BEM‑styled HTML with built‑in JS behavior.

Accordion (Block)

  • Path: src/blocks/accordion/
    • Definition: src/blocks/accordion/block.json (name: chisel/accordion)
    • Editor UI: src/blocks/accordion/edit.js
    • Save output: src/blocks/accordion/save.js
    • Front‑end JS: src/blocks/accordion/view.js
    • Inner item: src/blocks/accordion/accordion-item.js (name: chisel/accordion-item)
  • Attributes (chisel/accordion):
    • closeOthers:boolean (default false) — close other items when one opens
    • firstOpen:boolean (default false) — open first item on load
    • titleTag:string (default h3) — tag shared with items via context
  • Behavior
    • view.js attaches to .js-accordion and toggles .js-accordion-item with a height animation.
    • Flags:
      • has-first-open opens the first item on init.
      • has-close-others ensures only one item stays open.
    • Uses native <details>/<summary> for good baseline accessibility.
  • Editor usage
    • Insert “Accordion” block.
    • Configure “Title tag”, “First item open”, “Close other items” in the sidebar.
    • Add one or more “Accordion Item” inner blocks. Each item:
      • Attributes: title (string), titleTag (auto‑injected from parent via context).
      • Content: any blocks inside the item’s content area.
  • Styling hooks
    • Block: b-accordion
    • Elements: b-accordion__item, b-accordion__item-header, b-accordion__item-title, b-accordion__item-content
    • State: is-open applied by JS during animation
    • Optional: has-first-open, has-close-others on the wrapper
    • Editor styles: src/blocks/accordion/editor.scss
    • Front styles: src/blocks/accordion/style.scss

Slider (ACF Block rendered via Twig)

  • Path: src/blocks-acf/slider/
    • Template: src/blocks-acf/slider/slider.twig
    • ACF schema: src/blocks-acf/slider/acf-json/group_66462c70b851f.json
    • Renders Twig component: views/components/slider.twig
    • Helper for data attributes: inc/WP/Twig.php::slider_prepare_params()
  • ACF fields
    • Slides (repeater) acf_block_slider_slides[]
      • Image: acf_bs_image (image ID)
    • Settings (cloned group group_66d5a4ebb41cd, exposed as fields.slider_options)
      • slider_settings (multi‑select flags): arrows, dots, loop, autoplay, thumbnails
      • If dots: slider_settings_dynamic_dots (yes/no)
      • If autoplay: slider_settings_autoplay_timeout (ms)
      • If thumbnails: slider_settings_thumbnails_no (int)
  • Twig rendering flow
    • slider.twig builds slides_html from ACF slides:
      • Each slide is <div class="b-slider__slide swiper-slide" …> with image HTML via get_responsive_image().
      • If “thumbnails” is enabled, each slide gets data-thumbnail-url (medium size).
    • It then includes the component: views/components/slider.twig:
{% include 'components/slider.twig' with {
  slides_html,
  params: {
    'slides-per-view': 1,
    block_settings: fields.slider_options
  }
} %}
Twig
  • slider_prepare_params(params) merges defaults and maps block_settings.slider_settings flags into data attributes:
    • arrows → data-arrows=”yes”
    • dots → data-dots=”yes” (+ optional data-dots-dynamic=”1″)
    • loop → data-loop=”yes”
    • autoplay → data-autoplay=”yes” and data-autoplay-timeout=”{ms}”
    • thumbnails → data-thumbnails=”{count}”
    • Pass‑through params (e.g., slides-per-view) become data‑attributes as well.
  • Behavior and dependencies
    • Expects Swiper.js CSS/JS present globally. Ensure the asset is registered/enqueued in your build.
    • Thumbnails navigation is supported when thumbnails is enabled; slides carry data-thumbnail-url used by the UI.
  • Editor usage
    • Insert “Slider” (ACF) block.
    • Add slides (images).
    • Configure Settings:
      • Enable arrows/dots/loop/autoplay/thumbnails as needed.
      • If dots: choose “dynamic dots”.
      • If autoplay: set “timeout” (ms).
      • If thumbnails: set number of visible thumbs.
  • Styling hooks
    • Block container: b-slider__inner
    • Component/JS: c-slider, js-slider, js-slider-container
    • Slides: b-slider__slide swiper-slide
    • Thumbnails (if used): slide data-thumbnail-url attribute for rendering thumbs list.
  • File references
    • src/blocks-acf/slider/slider.twig
    • src/blocks-acf/slider/acf-json/group_66462c70b851f.json
    • views/components/slider.twig
    • inc/WP/Twig.php::slider_prepare_params()

Notes and integration

  • JS initialization
    • Accordion: auto‑initialized via view.js on DOMContentLoaded for .js-accordion.
    • Slider: initialize Swiper instances targeting .js-slider/.js-slider-container using the data attributes produced by slider_prepare_params().
  • Server‑side rendering
    • Accordion is a native block: saved markup is static; behavior is pure front‑end JS.
    • Slider is an ACF block: server renders Twig (slider.twig), which composes the generic slider component plus data attributes derived from ACF settings.
  • Extensibility tips
    • Add new slider options: extend ACF schema, map in slider_prepare_params(), and read from data attributes in your Swiper init.
    • Customize accordion behavior: tweak view.js (e.g., animation timing) and corresponding styles.

Do you like Chisel?

Give it a star on GitHub!