{"id":19107833,"url":"https://github.com/alleyinteractive/wp-component-library","last_synced_at":"2026-01-20T20:09:20.401Z","repository":{"id":40291549,"uuid":"415099725","full_name":"alleyinteractive/wp-component-library","owner":"alleyinteractive","description":"A plugin to list and preview components from the active theme's component library in the WordPress admin.","archived":false,"fork":false,"pushed_at":"2026-01-19T16:17:50.000Z","size":405,"stargazers_count":6,"open_issues_count":7,"forks_count":0,"subscribers_count":24,"default_branch":"main","last_synced_at":"2026-01-19T22:43:56.322Z","etag":null,"topics":["wordpress","wordpress-plugin"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alleyinteractive.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-10-08T19:07:18.000Z","updated_at":"2025-11-18T19:24:22.000Z","dependencies_parsed_at":"2025-04-30T18:52:00.138Z","dependency_job_id":"09a74f6b-f3a9-481b-ae54-0f8ccbaee955","html_url":"https://github.com/alleyinteractive/wp-component-library","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/alleyinteractive/wp-component-library","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-component-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-component-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-component-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-component-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alleyinteractive","download_url":"https://codeload.github.com/alleyinteractive/wp-component-library/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-component-library/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28612159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T18:56:40.769Z","status":"ssl_error","status_checked_at":"2026-01-20T18:54:26.653Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["wordpress","wordpress-plugin"],"created_at":"2024-11-09T04:14:09.724Z","updated_at":"2026-01-20T20:09:20.396Z","avatar_url":"https://github.com/alleyinteractive.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WP Component Library\n\n\u003e [!NOTE]\n\u003e This plugin is no longer actively maintained. For a more modern approach to building\n\u003e component-based WordPress themes, consider using\n\u003e [`create-wordpress-plugin](https://github.com/alleyinteractive/create-wordpress-plugin)`\n\u003e to scaffold blocks for a block-based theme.\n\nA plugin to list and preview components from the active theme's component\nlibrary in the WordPress admin. Also provides helper functions for loading\ncomponents in your theme so you can build with components atomically, similar\nto how you can work with components in React.\n\n## Usage\n\nThis plugin will add a new area to the WordPress admin called\n\"Component Library.\" By default, this area will be accessible to anyone with\nthe `manage_options` capability, but this is filterable.\n\nUpon visiting the Component Library page, any components configured in the\nactive theme's `components` folder within the root of the theme according to\nthe standards laid out below will be displayed with information from the\nREADME and one or more live previews based on values in the `examples` key in\nthe `component.json` file in the component folder.\n\n## Directory Structure\n\nIn order for this plugin to pick up and display your components, you need to\nestablish the following directory structure:\n\n* wp-content\n  * themes\n    * {theme-name}\n      * components\n        * {group name} (optional)\n            * {component-name}\n            * component.json - A JSON file containing a title for the component,\n                props for the component, and example data for admin previews. See\n                below for more info.\n            * README.md - An explanation of what the component is, what props it\n                accepts, and how it should be used.\n            * style.scss - Optional. A stylesheet that defines styles for the\n                component. See the Loading Styles section below for more info.\n            * template.php - The file that renders the component.\n\nFor examples, look in the\n[components directory](components).\n\n### `component.json`\n\nA JSON file with three top-level keys: `examples`, `props`, and `title`.\n\n#### `examples`\n\nAn array of objects, each of which should have a `title` property that defines\nthe title for the example in the admin, and a `props` property that contains\nan object with key/value pairs for prop values.\n\n#### `props`\n\nAn array of objects defining props for the component, the spec for which is as follows:\n\n| Property       | Default  | Required | Type   | Description                                                                               |\n|----------------|----------|----------|--------|-------------------------------------------------------------------------------------------|\n| allowed_values | []       | No       | array  | If the `type` is set to `enum`, the list of allowed values.                               |\n| default        | ''       | No       | string | The default value to use if none is provided in component props.                          |\n| description    |          | Yes      | string | The description of the component to display in the admin.                                 |\n| required       | false    | No       | bool   | Whether a value for the prop is required or not.                                          |\n| type           | 'string' | No       | string | The prop type. Possible values are 'array', 'bool', 'enum', 'number', 'object', 'string'. |\n\n#### `title`\n\nA string that names the component when it is viewed in the admin. For example,\n\"Button.\"\n\nTitles may include subgroups separated by a `/`, for example, \"Elements/Button\". This will organize the display of components in the component viewer by those subgroups.\n\n#### Props for `core/*` blocks\n\nAll supported core blocks include a `raw` prop that you can include into your `component.json` file if you would like to extend the functionality of the block within your theme/plugin utilizing the block's original attributes.\n\nMany of the core blocks implicity pass their HTML attributes as potential props that can be utlized by a component, but aren't explicitly defined in the examples. This is to provide support for updates within WordPress that may introduce new functionality in the future.\n\nOnly props that are explicitly declared in your `component.json` file will be passed to `template.php`. You can add a temporary logging statement to the `wpcl_component()` function to debug potential props.\n\n\u003e Potential enchancement: expose this information 👆️ if a constant is declared similar to WP_DEBUG.\n\n#### Example\n\nAn example `component.json` can be found in\n[tests/components/button/component.json](tests/components/button/component.json).\n\n### `README.md`\n\nThe file that describes your component. The examples and props sections of the\ndocumentation will be dynamically compiled from the definitions in\n`component.json`, but the README will be used for a long description of what\nthe component is used for.\n\n#### Example\n\nAn example `README.md` can be found in\n[tests/components/button/README.md](tests/components/button/README.md).\n\n### `style.scss`\n\nA stylesheet that contains styles that are scoped to the component. Whether and\nhow you work with these stylesheets is up to you, as they will need to be\nintegrated into your theme's asset builder. However, globbing them using\n[node-sass-glob-importer](https://www.npmjs.com/package/node-sass-glob-importer)\nis a good idea, as it will allow you to create styles for new components simply\nby adding a stylesheet to a directory rather than needing to import the\nstylesheet into an index file.\n\n#### Example\n\nAn example `style.scss` can be found in\n[tests/components/button/style.scss](tests/components/button/style.scss).\n\n### `template.php`\n\nThe template file behaves like a normal template file called by\n`get_template_part`. It has access to all of the same variables. However, the\nprops system will enforce props rules and set default values for you, so the\n`$args` variable that contains the arguments for the template is a little\nsmarter than the WordPress default.\n\n#### Example\n\nAn example `template.php` can be found in\n[tests/components/button/template.php](tests/components/button/template.php).\n\n## Templating Functions\n\nThis plugin contains a number of helpful functions for use in writing\nWordPress templates using components that you define according to the specs\nabove.\n\n### wpcl_component\n\nThe primary function used for working with components. Accepts two arguments:\na component name and an optional array of props. Loads and outputs the\ncomponent's template file after getting values for all props, either from what\nwas provided in the props array, or using default values for each prop.\n\n#### Example Usage\n\n```php\nwpcl_component( 'button', [ 'href' =\u003e 'https://www.example.org', 'text' =\u003e 'Visit example.org' ] );\n```\n\n### wpcl_attributes\n\nAccepts an array of key/value pairs to set as attributes on an HTML element\nand safely outputs them. Optionally, you can pass the `$args` variable as the\nsecond parameter and the function will intelligently merge props with default\nvalues. It is recommended to use this approach for attributes on the root\nelement of a component to enable support for setting the `id` and `class` props.\n\nThe `class` attribute accepts either a normal string of classes, or an array of\narguments in the same fashion as the\n[classnames npm package](https://www.npmjs.com/package/classnames).\nThis is useful for applying multiple classes, conditional classes, derived\nclasses, and merging a set of classes with class names that may have been passed\nto a component via props.\n\n#### Example Usage\n\n```php\n\u003ca\n    \u003c?php\n        wpcl_attributes(\n            [\n                'class' =\u003e [ 'class-1', [ 'class-2', 'class-3' ], [ 'class-4' =\u003e $maybe_include ] ],\n                'href'  =\u003e 'https://www.example.org/',\n            ],\n            $args\n        );\n    ?\u003e\n\u003e\n```\n\n### wpcl_markdown\n\nSafely converts a markdown string to HTML and outputs it.\n\n#### Example Usage\n\n```php\nwpcl_markdown( '## This will become an h2' );\n```\n\n### wpcl_blocks\n\nAttempts to render `core/*` blocks using components defined in the theme. If no component\nis found, then the block's normal renderer is used instead.\n\nYou can also call this function recursively if your block contains `innerBlocks` that you would also like to handle.\n\n#### Example Usage\n\n```php\n// single.php or in The Loop™. Defaults to blocks from post_content\nwpcl_blocks();\n\n// Or call it anywhere, passing in block definitions from a function like parse_blocks()\nwpcl_blocks( $blocks );\n```\n\n## Loading Styles\n\nIf you are using styles that are scoped to your components (e.g., a style.scss\nfile in each component directory) you will need to make sure that you are\nrunning a build of those component styles that is loaded in the admin via the\n`admin_enqueue_scripts` hook so the styles are previewable in the admin view.\n\n## Local Development\n\nThe admin views for this plugin are produced using components built using this\nplugin, which allows us to \"eat our own dog food,\" or use the plugin to develop\nthe plugin. In order to switch the behavior of the plugin from previewing\ncomponents in the active theme to previewing the components that are used in\nthis plugin, simply append `\u0026dogfooding=1` to the admin URL for the components\nview.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falleyinteractive%2Fwp-component-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falleyinteractive%2Fwp-component-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falleyinteractive%2Fwp-component-library/lists"}